antoniny/api-localidades repository overview

⁠API - Localidades

Projeto criado para realização de um desafio. Disponibiliza três url's de api para extração e consulta de dados referente a estados e municípios. Através das urls publicadas as consultas serão realizadas em api externa publica do IBGE e retornado os dados transformados em Json/CSV.

⁠Visão geral

O projeto é uma aplicação back-end java com objetivo de demonstrar a construção de uma API utilizando os frameworks Spring Boot⁠, Spring MVC⁠ e Spring Web⁠ em conjunto.

⁠Temas

1 - Tecnologias

2 - Contratos de API

3 - Setup da aplicação (local)

4 - Instalação da aplicação

5 - DockerHub

6 - Instalação da aplicação via build/compilação

⁠1 - Tecnologias

• Spring Boot⁠ é uma ferramenta que simplifica a configuração e execução de aplicações Java stand-alone, com conceitos de dependências “starters”, auto configuração e servlet container embutidos é proporcionado uma grande produtividade desde o start-up da aplicação até sua ida a produção.

• Spring MVC⁠ é um framework já consolidado no mercado, que a partir da versão fornece mecanismos simplificados para a criação de APIs RESTful através de anotação, além disso, também possui recursos de serialização e deserialização de objetos de forma transparente

• Spring Web⁠ é um produto da comunidade Spring focado na criação de serviços da Web controlados por documentos.

Estrutura do projeto

br.com.antoniny.localidades
config
controller.v1
integration
service
resources

Diagrama de Classes

⁠2 - Contratos de API

Este projeto publica 3 urls para consumo e utiliza internamente 2 urls externas para coleta de dados.

Seguem abaixo as API's do projeto:

⁠Host Local

• /api/v1/localidades (GET)
  • Retorna um Json com todos os municípios/estados da federação em layout específico através de busca online em api's do IBGE.
  exemplo:

  λ curl -X GET --header 'Accept: application/json' 'http://localhost:8080/api/v1/localidades'
  [
      {
          "idEstado": 11,
          "siglaEstado": "RO",
          "regiaoNome": "Norte",
          "nomeCidade": "Alta Floresta D'Oeste",
          "nomeMesorregiao": "Leste Rondoniense",
          "nomeFormatado": "Alta Floresta D'Oeste/RO"
      },
      {
      ...
      ...  
  ]
  

  Copy

• /api/v1/localidades/csv (GET)

  • Retorna um text/CSV com todos os municípios/estados da federação em layout específico através de busca online em api's do IBGE.

  Disponibiliza download de arquivo *.csv com todos os dados retornados.

  exemplo:

  λ curl http://localhost:8080/api/v1/localidades/csv
  
  > download file localidades.csv
   
  idEstado;siglaEstado;regiaoNome;nomeCidade;nomeMesorregiao;nomeFormatado
  11;RO;Norte;Alta Floresta D'Oeste;Leste Rondoniense;Alta Floresta D'Oeste/RO
  11;RO;Norte;Ariquemes;Leste Rondoniense;Ariquemes/RO
  11;RO;Norte;Cabixi;Leste Rondoniense;Cabixi/RO
  ...
  ...
  ... 
  

  Copy

• /api/v1/localidades/cidades/id (GET)

  • Retorna o id IBGE da cidade pesquisada atráves de uma parâmetro "nomeCidade" através de busca online em api's do IBGE.

  Devido ao fato de exitir em nossa federação cidades homônimas, essa irá retornar o id de todas essas cidades.

  exemplo:

  λ curl http://localhost:8080/api/v1/localidades/cidades/id?nomeCidade=Palhoça
  [
    {
      "idCidade": 4211900
    }
  ]
  
  

  Copy

Layout(Json/Csv):

 idEstado
 siglaEstado
 regiaoNome
 nomeCidade
 nomeMesorregiao
 nomeFormatado {cidade/UF}   

⁠Host Externo - Consumo interno da aplicação

Este projeto utiliza duas url's para consulta externa.

Consulta de Estados⁠

Consulta de Municípios⁠

Documentação⁠

⁠3 - Setup da aplicação (local)

⁠Pré-requisito

Antes de rodar a aplicação é preciso garantir que as seguintes dependências estejam corretamente instaladas:

Java 8
Maven 3.1.0

⁠4 - Instalação da aplicação

Primeiramente, faça o clone do repositório:

https://github.com/antoniny/api-localidades.git

Acesse a pasta do projeto:

cd api-localidades

É preciso compilar o código e baixar as dependências do projeto:

mvn clean package

Finalizado esse passo, vamos iniciar a aplicação:

mvn spring-boot:run

A api já deverá estar disponível em

Swagger: http://localhost:8080/swagger-ui.html#/⁠

Localidades : Obtem informações de localidadesShow/HideList OperationsExpand Operations

 GET /api/v1/localidades
 Obtém os municípios cadastros no IBGE no formato JSON.
 
 GET /api/v1/localidades/cidades/id
 Obtém o(s) código(s) ibge(id) do(s) município(s) através do nome do município.
 
 GET /api/v1/localidades/csv
 Obtém os municípios cadastros no IBGE no formato CSV.
 
 [ base url: / , api version: 1.0.0 ]

⁠5 - DockerHub

Repositorio DockerHub⁠ -> Acesso ao repositório do projeto no DockerHub

⁠Executar servidor via Docker Client - pull image

Pré-requisito

Doker Client instalado e em execução

Get Docker⁠

Comandos para iniciar o servidor

##1 - Realiza o download e inicia o servidor em http://localhost:8080/swagger-ui.html

docker run --name api-localidades -it -p 8080:8080 antoniny/api-localidades:latest

##Nota: Caso não deseja a exibição de logs do servidor em seu terminal, execute o comando abaixo ( -d
docker run --name api-localidades -itd -p 8080:8080 antoniny/api-localidades:latest

##2 - Stop servidor

docker stop api-localidades

##3 - Listar imagens

docker images

##4 - Listar container ativos

docker container ls

##4 - Deletar container / image

 docker rm api-localidades
 docker rmi -f antoniny/api-localidades

⁠6 - Instalação da aplicação via build/compilação

Baixar as dependência e criar imagem da aplicação

Considerando sistema operacional windows com docker cli instalado.

Nota 1: Docker Cli deve estar ativo (Container Linux)

Nota 2: Ativar -> Docker Cli Win > Settings > General > Expose daemon on tcp://localhost:2375 without TLS

Necessário para que o Maven consiga gerar a imagem no docker.

mvn clean package docker:build

Executar container da aplicação

docker run --name api-localidades -it -p 8080:8080 antoniny/api-localidades:latest

.