Uma visão de um iniciante sobre APIs
- #API Rest
Introdução:
Neste artigo, vamos aprender o que é e para que serve uma API (Interfaces de Programação de Aplicativos) desempenham um papel fundamental no mundo da programação, permitindo a comunicação e interação entre diferentes sistemas. Abordaremos os principais aspectos relacionados a APIs, desde a definição e funcionalidade básica até tópicos avançados, como autenticação, segurança, documentação e performance. Além disso, exploraremos o desenvolvimento de uma API em Java, utilizando o framework Spring Boot como exemplo.
Teremos o seguinte trajeto:
- o que é e para que serve uma api;
- como funciona uma api
- como criar uma api em java;
- o que é uma API RESTful
- o que são endpoints e rotas de uma api
- como consumir uma api em java
- autenticação e autorização de uma api (token, OAuth e JWT)
- o que é formato JSON
- Como é manipulação de JSON;
- o que é e como usar Spring MVC
- como documentar sua api (Swagger UI, Springfox, etc)
1. O que é e para que serve uma API?
Uma API é um conjunto de regras e protocolos que permite a comunicação entre diferentes softwares. Ela define como os diferentes componentes de um sistema podem interagir uns com os outros. As APIs podem ser usadas para diversos propósitos, tais como: integração de sistemas, compartilhamento de dados, desenvolvimento de aplicativos móveis e web, entre outros. Por exemplo, o sistema de software do instituto meteorológico contém dados meteorológicos diários. A aplicação para a previsão do tempo em seu telefone “fala” com esse sistema por meio de APIs e mostra atualizações meteorológicas diárias no telefone.
No contexto de APIs, a palavra Aplicação refere-se a qualquer software com uma função distinta. A interface pode ser pensada como um contrato de serviço entre duas aplicações. Esse contrato define como as duas se comunicam usando solicitações e respostas. A documentação de suas respectivas APIs contém informações sobre como os desenvolvedores devem estruturar essas solicitações e respostas.
2. Como funciona uma API?
Como já falado pouco acima, uma API funciona como uma ponte entre dois ou mais sistemas. Ela expõe um conjunto de funcionalidades e operações que podem ser acessadas e utilizadas por outros sistemas. Geralmente, as APIs são disponibilizadas através de endpoints, que são URLs específicas que respondem a requisições e retornam os dados ou executam as ações solicitadas. Exemplo o cliente é a parte que solicita os dados ou serviços da API, e o servidor é a parte que fornece os dados ou serviços. As requisições e respostas seguem um protocolo de comunicação, que geralmente é o HTTP (Hypertext Transfer Protocol). O HTTP define os métodos (verbos) que indicam a ação desejada pelo cliente, como GET, POST, PUT, DELETE, etc. O HTTP também define os códigos de status que indicam o resultado da requisição, como 200 (OK), 404 (Not Found), 500 (Internal Server Error), etc.
Existem quatro maneiras diferentes pelas quais as APIs podem funcionar, dependendo de quando e por que elas foram criadas:
- APIs SOAP
Essas APIs usam o Simple Object Access Protocol (Protocolo de Acesso a Objetos Simples). Cliente e servidor trocam mensagens usando XML. Esta é uma API menos flexível que era mais popular no passado.
- APIs RPC
Essas APIs são conhecidas como Remote Procedure Calls (Chamadas de Procedimento Remoto). O cliente conclui uma função (ou um procedimento) no servidor e o servidor envia a saída de volta ao cliente.
- APIs WebSocket
A API de WebSocket é outro desenvolvimento de API da Web moderno que usa objetos JSON para transmitir dados. Uma API WebSocket oferece suporte à comunicação bidirecional entre aplicativos cliente e o servidor. O servidor pode enviar mensagens de retorno de chamada a clientes conectados, tornando-o mais eficiente que a API REST.
- APIs REST
Essas são as APIs mais populares e flexíveis encontradas na Web atualmente. O cliente envia solicitações ao servidor como dados. O servidor usa essa entrada do cliente para iniciar funções internas e retorna os dados de saída ao cliente.
Tipos de API:
- Privada : A API é usada apenas internamente. Isso oferece às empresas um maior controle.
- Parceiros: A API é compartilhada com parceiros de negócios específicos. Isso pode fornecer fluxos de receita adicionais sem comprometer a qualidade.
- Pública: A API é disponibilizada para todos. Terceiros podem desenvolver aplicações que interajam com a sua API e isso pode se tornar uma fonte de inovação.
- Composta:: Estas combinam duas ou mais APIs distintas para atender a requisitos ou comportamentos complexos do sistema.
3. Como criar uma API em java?
Para criar uma API em Java, podemos utilizar o framework Spring Boot. O Spring Boot é uma ferramenta poderosa que simplifica o desenvolvimento de aplicativos Java, um dos mais usados para desenvolver aplicações web em Java, incluindo a criação de APIs. Ele fornece recursos como injeção de dependência, configuração automática e um servidor embutido, permitindo que o desenvolvedor se concentre nas funcionalidades da API. O Spring Boot, oferece recursos como autoconfiguração, dependências gerenciadas, monitoramento, testes, segurança, etc e é possível criar uma API RESTful rapidamente, seguindo as melhores práticas de desenvolvimento.
4. O que é uma API RESTful?
Uma API RESTful é um estilo de arquitetura para desenvolvimento de APIs, baseado nos princípios do REST (Representational State Transfer). Ela utiliza os verbos HTTP tem sido usado desde 1990 e a versão atual do protocolo é o HTTP/3. O protocolo define oito métodos que determinam ações a serem efetuadas no momento da requisição de algum recurso ao servidor. Desses oito, os 4 mais utilizados são:
- GET: método utilizado para ler e recuperar dados. Requisita uma representação do recurso especificado e retorna essa representação.
- POST: método utilizado para criar um novo recurso. Envia dados ao servidor. O tipo do corpo da solicitação é indicado pelo cabeçalho Content-Type.
- PUT: cria um novo recurso ou substitui uma representação do recurso de destino com os novos dados. A diferença entre PUT e POST é que PUT é idempotente: ao chamá-lo uma ou várias vezes sucessivamente o efeito é o mesmo, enquanto se chamar o POST repetidamente pode ter efeitos adicionais. Por exemplo, se criarmos um produto com POST, se a URL definida na API for chamada 20 vezes, 20 produtos serão criados e cada um deles terá um ID diferente. Já o com o PUT se você executar a URL definida na API 20 vezes, o resultado tem que ser o mesmo: o mesmo produto atualizado 20 vezes.
- DELETE: exclui o recurso.
5. O que são Endpoints e rotas de uma API?
Pode ser considerado um endpoint qualquer dispositivo que esteja fisicamente conectado em uma rede. Por exemplo: laptops, desktops, smartphones, tablets, servidores e ambientes virtuais.
As rotas são conceitos fundamentais relacionados à maneira como as solicitações são feitas e os recursos são acessados.
Um endpoint é uma URL específica ou um que identifica um recurso específico em uma API. As rotas são os caminhos que levam a esses endpoints. Em outras palavras, as rotas são os URLs que os clientes usam para acessar os endpoints da API.
Cada rota está associada a um método HTTP específico (GET, POST, PUT, DELETE, etc.) e é responsável por realizar uma operação específica no recurso relacionado.
6. Como consumir uma API em Java?
Para consumir uma API em Java, também existem diversas opções de bibliotecas e frameworks que facilitam o envio e o recebimento de requisições HTTP. Algumas delas são:
- - HttpClient: uma classe nativa do Java que permite criar e executar requisições HTTP de forma simples e eficiente.
- - OkHttp: uma biblioteca externa que oferece recursos como conexões persistentes, compressão, cache, redirecionamento, etc.
- - Retrofit: um framework externo que permite criar clientes HTTP baseados em interfaces Java anotadas com as especificações da API.
- - RestTemplate: uma classe do Spring Framework que permite enviar requisições HTTP sincronamente ou assincronamente.
Essas bibliotecas permitem fazer requisições HTTP para os endpoints da API, enviar parâmetros, receber as respostas e processar os dados retornados.
Exemplo:
o Web Service REST utilizando o framework RESTEasy, enquanto que o cliente, ou seja, a aplicação que irá consumir o serviço, será implementada utilizando a própria linguagem Java.
<?xml version="1.0" encoding="UTF-8"?>
<banda>
<nome>Led Zeppelin<nome>
<album>
<nome>Led Zeppelin</nome>
<ano>1969</ano>
<musicas>
<musica>
<nome>Good Times Bad Times</nome>
</musica>
<musica>
<nome>You Shook Me</nome>
</musica>
</musicas>
</album>
</banda>
O Web Service Rest, conforme pode ser visto pelo XML, expõe algumas informações sobre uma determinada banda de música. No exemplo, a nossa banda é o Led Zeppelin (yeah, essa eu curto). A banda deve ter um nome e um álbum. O álbum por sua vez, tem um nome, o ano de lançamento, e como todo bom álbum, tem músicas . Pelo fato do XML ser uma linguagem estruturada, podemos ter uma idéia de como serão nossas classes Java. A Listagem 2 mostra a classe Banda, a Listagem 3 mostra a classe Album, e a Listagem 4 mostra a classe Musica, todas já com as anotações JAXB correspondentes.
Listagem 2: Classe Banda
@XmlRootElement(name="banda")
public class Banda {
private String nome;
private Album album;
@XmlElement
public String getNome() {
return nome;
}
public void setNome(String nome) {
this.nome = nome;
}
@XmlElement
public Album getAlbum() {
return album;
}
public void setAlbum(Album album) {
this.album = album;
}
}
Listagem 3: Classe Album
public class Album {
private String nome;
private int ano;
private List<Musica> musicas;
@XmlElement
public String getNome() {
return nome;
}
public void setNome(String nome) {
this.nome = nome;
}
@XmlElement
public int getAno() {
return ano;
}
public void setAno(int ano) {
this.ano = ano;
}
@XmlElement
@XmlElementWrapper
public List<Musica> getMusicas() {
return musicas;
}
public void setMusicas(List<Musica> musicas) {
this.musicas = musicas;
}
}
Listagem 4: Classe Musica
public class Musica {
private String nome;
@XmlElement
public String getNome() {
return nome;
}
public void setNome(String nome) {
this.nome = nome;
}
}
Para realizar o exemplo deste artigo, é necessário que se tenha o servidor de aplicação JBoss AS7 instalado e configurado e a IDE eclipse para JEE. Vamos iniciar nossa aplicação criando um novo Dynamic Web Project chamando-o de musicApp, e informaremos à IDE que desejamos que gere o nosso Deployment Descriptor. Após isso, clique em finish.
Antes de iniciar, configure o RESTEasy no Deployment Descriptor da aplicação. A Listagem 5 mostra o que deve ser adicionado no Deployment Descriptor para configuração do RESTEasy. Após isso, crie um pacote chamado domain, e adicione as classes Banda, Album e Musicas, exibidas logo acima.
Listagem 5: Configuração a ser adicionada no web.xml
<context-param>
<param-name>resteasy.scan</param-name>
<param-value>true</param-value>
</context-param>
<servlet>
<servlet-name>resteasy-servlet</servlet-name>
<servlet-class>
org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>resteasy-servlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
O próximo passo é criar a classe BandaService e um pacote chamado resource. Esta classe é a responsável por expor o serviço Rest, e pode ser vista na Listagem 6.
@Path("/banda")
public class BandaService {
@GET
@Path("/get")
@Produces("application/xml")
public Banda getUserInXML() {
Banda banda = new Banda();
banda.setNome("Led Zeppelin");
Album album = new Album();
album.setAno(1969);
album.setNome("Led Zeppelin");
Musica musica1 = new Musica();
Musica musica2 = new Musica();
List<Musica> musicas = new ArrayList<Musica>();
musica1.setNome("Good Times Bad Times");
musica2.setNome("You Shook Me");
musicas.add(musica1);
musicas.add(musica2);
album.setMusicas(musicas);
banda.setAlbum(album);
return banda;
}
}
Estamos quase lá. Agora só falta nossa classe cliente, a classe que consumirá o serviço. Para isso crie uma classe chamada de ClienteJava, conforme pode ser vista na Listagem 7. A estrutura da nossa aplicação pode ser vista na figura 3.
Listagem 7: Classe ClienteJava
public class ClienteJava {
private static int HTTP_COD_SUCESSO = 200;
public static void main(String[] args) throws JAXBException {
try {
URL url = new URL("http://localhost:8080/musicApp/banda/get");
HttpURLConnection con = (HttpURLConnection) url.openConnection();
if (con.getResponseCode() != HTTP_COD_SUCESSO) {
throw new RuntimeException("HTTP error code : "+ con.getResponseCode());
}
BufferedReader br = new BufferedReader(new InputStreamReader((con.getInputStream())));
JAXBContext jaxbContext = JAXBContext.newInstance(Banda.class);
Unmarshaller jaxbUnmarshaller = jaxbContext.createUnmarshaller();
Banda banda = (Banda) jaxbUnmarshaller.unmarshal(br);
System.out.println("------ Dados da Banda -------- \n");
System.out.println("Nome da Banda : "+banda.getNome());
System.out.println("Nome do Álbum : "+banda.getAlbum().getNome());
System.out.println("Ano de Lançamento: "+banda.getAlbum().getAno());
int count = 1;
for (Musica musica : banda.getAlbum().getMusicas()) {
System.out.println("Música "+ count +": "+ musica.getNome());
count++;
}
con.disconnect();
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
7. Autenticação e autorização de uma api (token, OAuth e JWT)?
A autenticação e autorização de uma API são fundamentais para garantir a segurança dos dados e controlar o acesso aos recursos. O uso de tokens, OAuth e JWT (JSON Web Tokens) são métodos comuns para autenticação e autorização em APIs. Tokens são utilizados para identificar e autenticar usuários, enquanto o OAuth é um protocolo de autorização que permite que usuários concedam permissões a aplicativos de terceiros. JWT é um formato compacto e seguro para representar informações entre partes como um objeto JSON.
- Token: um código gerado pelo servidor após o usuário se autenticar com suas credenciais (usuário e senha). O token deve ser enviado pelo cliente em cada requisição subsequente para provar sua identidade e obter acesso aos recursos.
- OAuth: um protocolo padrão que permite delegar a autenticação e a autorização de uma API para um provedor externo, como Google, Facebook, Twitter, etc. O OAuth permite que o usuário autorize o acesso da API a seus dados sem compartilhar suas credenciais com a API.
- JWT (JSON Web Token): um tipo de token que contém informações codificadas sobre o usuário ou cliente que fez a requisição. O JWT é assinado digitalmente pelo servidor para garantir sua integridade e validade. O JWT pode ser usado para autenticar e autorizar o acesso aos recursos da API.
Cliente enviando requisição com dados de autenticação
Servidor envia o token assinado ao cliente
Usuário com token autenticado pode acessar endpoints restritos
8. O que é formato JSON?
JSON (JavaScript Object Notation) é um formato leve e legível por humanos para troca de dados. Ele é amplamente utilizado em APIs para representar objetos e estruturas de dados de forma organizada e compatível com diversas linguagens de programação.
9. Como é Manipulação de JSON?
A manipulação de JSON é comumente realizada em APIs. Em Java, podemos utilizar bibliotecas como o Gson, Jackson ou JSON-B para converter objetos Java em JSON e vice-versa. Essas bibliotecas oferecem métodos para realizar operações de leitura, escrita e manipulação de dados em formato JSON.
10. Como é usar o Spring MVC?
O Spring MVC (Model-View-Controller) é um módulo do Spring que permite o desenvolvimento de aplicativos web, incluindo a construção de APIs. Ele segue o padrão arquitetural MVC, onde o modelo representa os dados, a visão é responsável pela apresentação e o controlador trata as requisições e define o fluxo de execução. O Spring MVC fornece anotações e recursos que facilitam a criação de endpoints e rotas em APIs.
11. Como documentar sua API (Swagger UI, Springfox, etc.)
A documentação de uma API é essencial para que os desenvolvedores possam entender e utilizar corretamente seus recursos. Felizmente, existem diversas ferramentas disponíveis para facilitar a documentação de APIs. Duas das opções mais populares são o Swagger UI e o Springfox.
O Swagger UI é uma ferramenta que permite gerar uma documentação interativa para APIs. Ele analisa o código da API e extrai informações sobre os endpoints, parâmetros, respostas e outras informações relevantes. Com o Swagger UI, é possível visualizar a documentação em um formato amigável, com exemplos de requisições e respostas, facilitando a compreensão e o uso da API.
O Springfox, por sua vez, é uma biblioteca específica para o framework Spring que integra o Swagger com o Spring Boot. Ele automatiza o processo de geração da documentação da API, utilizando as anotações do Spring para extrair as informações necessárias. Com o Springfox, é possível configurar a documentação da API de forma simples e personalizada, adicionando descrições, tags e outras informações relevantes.
Além dessas ferramentas, existem outras opções para documentação de APIs, como o API Blueprint, o RAML (RESTful API Modeling Language) e o Postman.
Segue exemplo do Postman: Segue o link do repositório que se encontra o código fonte da nossa aplicação: https://github.com/AntonioMontanha/gerenciador-viagens,
- Collection: ela irá agrupar as pastas e as requisições.
- Folder: é realmente uma pasta, se utiliza para organizar as Requests.
- Request: são as requisições, se trata do que realmente será enviado para nossa API, ela possui alguns componentes que serão abordados abaixo.
- Verbo HTTP: o verbo que a requisicões está utilizando, muda conforme o que a requisição deseja fazer, normalmente temos: POST, GET, PUT e DELETE.
- URL: é o caminho que a requisição será enviada. Lembra dos caminhos definidos em nosso ViagemController?
- Environment: é o ambiente que está sendo utilizado, por enquanto entenda que ele pode ser usado como um conjunto de variáveis.
- Body: o corpo da request, aqui serão enviadas as informações que nosso método cadastrar (POST) irá utilizar para inserir viagens no sistema.
- Pré -request Script: são script que você pode escrever que serão executados antes da requisição ser enviada, por exemplo, você pode escrever algo que gere um CPF de forma randômica e atribuir em uma variável, então utilizar esta variável na requisição.
- Tests: aqui é onde serão escritos nossos testes.
- Nessa nossa nova Request vamos alterar o Verbo dela para POST, e vamos colocar a URL que irá acessar o caminho de nossa aplicação que cadastra viagens, no caso: http://localhost:8089/api/viagens/new .
- Temos então que informar um Body, que são as informações para serem inseridas, clique em Body.
- Selecione raw, para uma melhor visualização dos dados, onde está Text selecione JSON, isto criará uma variável em nossos Headers, dizendo que o tipo de informação que iremos trabalhar é JSON. Enfim como podemos ver temos nosso Body e nele o Local de Destino está com menos de 3 carácteres, é esperado que a nossa aplicação não insira estes dados e retorne uma mensagem de erro alertando da situação. Se clicarmos em SEND, que no caso envia a requisição para a aplicação.
- Quando enviamos, tivemos o retorno esperado, nossa Response nos devolveu um Status 400, que significa que tem algo errado com a requisição, e em seu Body nos alertou quanto ao tamanho mínimo do Local de Destino.
- Ok, mas e se quisermos automatizar isso? Para nunca mais precisar se preocupar com essa validação? Já pensou se todas as vezes que tivermos alguma alteração no código nós tivermos que criar novas requisições, ou então entrar em uma por uma e ir enviando para ver se nossas alterações não quebraram outras coisas? Bem não é necessário, se prestar atenção na imagem acima, de nossa Response, ao lado de Headers temos: Test Results: 2/2, ou seja dos dois testes que temos escritos para esta requisição, os dois passaram. Vamos ver estes testes então.
- Na aba Tests podemos escrever os testes automatizados da nossa aplicação. Eles são feitos em JavaScript, mas não é necessário conhecer a linguagem para realizar os testes, no canto direito quando você abre a aba de Tests possuem Snippets que vão te guiar para cada tipo de teste.
- Primeiro vamos verificar se o código retornado pela nossa response é 400. Então escrevemos:
- tests:[“Aqui dentro escrevemos o nome do nosso teste, veja como ficou na imagem la emcima] = responseCode.code === 400
- Se preferir pode acessar o Snippet “Status code: code is 200, ele irá montar um teste da seguinte forma:
- Bastaria mudar para 400, e também funciona, é fácil perceber que ele utiliza uma outra estrutura para os testes, ambas funcionam, eu estou utilizando a outra por ela ser mais simples de entender em um primeiro contato, mas utilize a que você se sentir mais confortável.
- Temos o teste do código da resposta feito, agora vamos fazer o da mensagem que a aplicação deve retornar. Para isso nós utilizamos o método parse, da seguinte forma:
- var response = JSON.parse(responseBody);
- nesse momento estamos atribuindo a uma variável response o corpo da resposta que obtivemos. O parse neste caso irá converter a string que foi retornada para um JSON, para que possamos acessar elementos específicos do JSON. Se olharmos o resposta dada pela nossa aplicação temos:
- ou seja, temos um errors, que no caso é uma lista dos erros que nossa aplicação encontrou, neste caso temos um só, mas se por exemplo não informarmos Data da Partida que é uma informação obrigatória também teremos:
- Então para automatizar esta validação escrevemos:
- tests[“Verifica a mensagem de validação do tamanho mínimo para Local de Destino”] = response.errors[0] === “Local de Destino deve estar entre 3 e 40 caracteres”;
- acima estamos utilizando aquela variável que declaramos (response), que no momento possui o JSON retornado em nossa resposta, acessando a lista de erros (.errors) e desta lista acessa o primeiro elemento dela ( [0] ), então verificar se o que está contido nesse elemento é a mensagem esperada.
- Agora realmente finalizando nosso post vamos abordar o teste de um cenário de sucesso, em que conseguimos cadastrar uma viagem no sistema. Em nossa Collection vamos criar uma pasta “Validações de Regra de Negócio” e vamos criar uma request dentro dela, esta será idêntica a request que utilizamos anteriormente com a diferença que informaremos dados válidos, no caso vamos utilizar o seguinte corpo:
- Com os dados informados acima esperamos que nossa viagem seja cadastrada, e esperamos em nossa resposta que a aplicação nos mostre os dados da viagem cadastrada, inclusive o id que foi atribuído a esta viagem.Então para testar esse cenário teremos a seguinte estrutura na aba Tests:
- de modo que na linha 1 verificamos se a resposta foi 201; na 5 verificamos se o campo id é diferente de nulo, ou seja se foi atribuido algum id para nossa viagem; fazemos as validações dos demais campos e por fim na linha 11 verificamos se a lista de erros está vazia. O Json retornado que contemplaria os testes acima ficaria da seguinte forma:
Conclusão:
Neste artigo, foi abordado as principais aspectos relacionados a APIs, desde sua definição básica até tópicos mais avançados, como autenticação, documentação e performance. Exploramos o desenvolvimento de uma API em Java, utilizando o Spring Boot como exemplo, e destacamos a importância de boas práticas, como o uso de APIs RESTful, a manipulação de JSON e a documentação adequada da API.
As APIs desempenham um papel fundamental na integração e comunicação entre sistemas, permitindo a construção de aplicativos modernos e escaláveis. Ao entender os conceitos e as melhores práticas relacionadas a APIs, os desenvolvedores estarão mais preparados para criar soluções eficientes, seguras e de alta qualidade.
Espero que este artigo tenha fornecido uma visão abrangente sobre APIs e tenha sido útil para o seu conhecimento.
Referencias:
https://aws.amazon.com/pt/what-is/api/
https://mari-azevedo.medium.com/construindo-uma-api-restful-com-java-e-spring-framework-46b74371d107
https://www.devmedia.com.br/consumindo-um-web-service-rest-com-java/27286
