Saber como realizar consultas a APIs é um conhecimento-chave para quem pretende desenvolver códigos capazes de se conectarem com o mundo. Atualmente é possível encontrar no mercado APIs que fazem basicamente tudo, e é por meio de uma consulta que você se conecta a elas. Nesse post vou demonstrar como realizar um requisição do tipo GET a uma API da maneira mais simples possível utilizando Java e o pacote GSON para trabalhar com o JSON retornado.
O que é uma API?
Antes de mais nada, caso o conceito de API ainda não seja muito claro para você, recomento que acesse o último post aqui do site onde foi esclarecido melhor a ideia do que é uma API.
Ter essa base de conhecimento será fundamental para você entender alguns tópicos deste post.
Algumas tecnicidades que é importante se atentar:
Para fins de compatibilidade antecipo que todo o código foi desenvolvido com o Java na versão1.8.0 e o pacote do GSON na versão 2.8.7.
Além disso para facilitar seu aprendizado disponibilizei o código usado no exemplo assim como o arquivo .jar da biblioteca do GSON num repositório do GitHub disponível clicando aqui.
Sobre a API que iremos consultar:
Como o intuito aqui é realizar uma consulta simples, no exemplo utilizaremos uma API bem simples de consulta de CRM disponível aqui. Essa API apenas espera que sejam enviados na requisição os atributos da pesquisa referente ao médico procurado e a mesma retorna os dados do médico correspondente em formato JSON.
É importante se atentar que para realizar consultas a esta API é necessário realizar um cadastro simples no site da API de modo que eles forneçam um token para monitorar a quantidade de consultas que estão sendo feitas, neste caso, é possível realizar até 100 consultas de maneira gratuita. Além disso, recomendo a utilização dessa API apensa para fins de aprendizado, comparando retornos dessa API com o retorno da mesma consulta mas na API oficial do Conselho Federal de Medicina percebi algumas incompatibilidades de informação.
Agora sim, mão na massa...
Após criada toda a estrutura básica de projeto Java, podemos iniciar a implementação da nossa consulta:
1 - Realizar o import das classes que utilizaremos no processo:
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.List;
import java.util.Scanner;
import com.google.gson.Gson;2 - Definir as Classes que receberão os objetos retornados da API:
Como citado acima, a API em questão irá retornar o resultado da nossa consulta em formato JSON, deste modo, para podermos manipular o retorno iremos implementar uma classe que receberá esse objeto JSON retornado da API e a partir dessa instanciação poderemos trabalhar com esse retorno mais facilmente..
class Dados_Retorno {
private final String url;
private final String total;
private final String status;
private final String mensagem;
private final String api_limite;
private final String api_consultas;
private final List<Item> item;
public Dados_Retorno(String url, String total, String status, String mensagem, String api_limite, String api_consultas, List<Item> item) {
this.url = url;
this.total = total;
this.status = status;
this.mensagem = mensagem;
this.api_limite = api_limite;
this.api_consultas = api_consultas;
this.item = item;
}
}Além dessa classe Dados_Retorno que criamos, observe que um dos atributos dessa classe é uma lista, é esperado que essa lista seja composta por outros objetos JSON. Deste modo, precisamos também definir uma classe que receba esses objetos:
class Item {
private final String tipo;
private final String nome;
private final String numero;
private final String profissao;
private final String uf;
private final String situacao;
public Item(String tipo, String nome, String numero, String profissao, String uf, String situacao) {
this.tipo = tipo;
this.nome = nome;
this.numero = numero;
this.profissao = profissao;
this.uf = uf;
this.situacao = situacao;
}
@Override
public String toString() {
//Retorna somente a situação cadastral que é o que queremos neste caso. Entretanto, todos os atributos da classe Item poderiam vir nesse retorno caso fosse necessário.
return situacao;
}
}
Neste caso, na linha destacada, apenas para testes definimos o retorno dessa classe como o atributo situação do cadastro apenas. Entretanto, todos os atributos de Item poderiam ser retornados caso isso fosse necessário.
3 - Definir o método de retorno da lista de Itens da classe Dados_Retorno:
public String getSituacaoCadastral() {
String[] itens = item.stream().map(String::valueOf).toArray(String[]::new);
if (itens == null) {
return "Médico não encontrado!";
} else {
return itens[0];
}Aqui, transformamos a nossa lista em um Array e já no próprio método fazemos a verificação se houve algum registro retornado na consulta realizada. Caso o número de registros seja diferente de 0 é retornado o registro em questão (ou melhor, apenas o atributo "situação" que foi o que definimos para ser retornado na classe Item).
4 - Realizar a consulta em si:
Após preparado o terreno para receber o retorno da nossa consulta podemos definir no main realizando a consulta como segue o código abaixo (Neste caso, para disponibilizar o código inteiro coloquei explicações sobre cada linha no próprio código.):
public class API_Return_Treatment {
public static void main(String[] args) {
Gson gson = new Gson(); //Instanciar Gson
Scanner sc = new Scanner(System.in); // Receber dados da consulta
System.out.print("TIPO: ");
String tipo = sc.next();
System.out.print("UF: ");
String uf = sc.next();
System.out.print("CADASTRO: ");
String nome = sc.next();
try {
//Abaixo, além de inserir os Inputs do usuário na URL de chamada da API, realizamos a conexão;
URL url = new URL("https://www.consultacrm.com.br/api/index.php?tipo="+tipo+"&uf="+uf+"&q="+nome+"&chave=1185342101&destino=json");
HttpURLConnection conector = (HttpURLConnection) url.openConnection();
conector.setDoOutput(true);
conector.setRequestMethod("GET");
if (conector.getResponseCode() != 200) { //Tratando um possível erro de conexão;
System.out.print("ERROR... HTTP error code : " + conector.getResponseCode());
}
BufferedReader br = new BufferedReader(new InputStreamReader((conector.getInputStream())));
String output, retorno="";
while ((output = br.readLine()) != null) {
retorno+=output; // Neste While é adicionado todo o retorno da API dentro da variável 'retorno'
}
Dados_Retorno dados_retorno = gson.fromJson(retorno, Dados_Retorno.class);//Pega o JSON que veio da API e coloca dentro da Classe que criei no começo;
System.out.println(dados_retorno.getSituacaoCadastral());
conector.disconnect();
}
catch (Exception e) {
e.printStackTrace();
}
}
}Perceba que no trecho destacado onde é inserida a chave de cadastro da API o cadastro inserido é o meu. Na sua consulta recomendo que você utilize o seu próprio para garantir que você usufrua dos 100 acessos mensais disponíveis gratuitamente.
OBS.:
Para ter acesso ao código de forma completa no GitHub clique aqui.
PRONTO!!!
Após executados os passos acima, você já pode colocar seu código para rodar e realizar suas próprias consultas a essa API.
Caso esse post tenha te ajudado de alguma maneira compartilhe esse conteúdo com seus amigos. Se tem alguma sugestão ou comentário sobre o post entre em contato que responderei o mais prontamente possível! Até a próxima!
Comentários