Apresentando API RESTFul. E o que ela tem de diferente do modelo REST

Saiba como funciona um dos principais padrões de comunicação entre aplicações web, o REST. Este artigo irá apresentá-lo, e te ajudar a saber se uma API é RESTFul .

As funcionalidades de uma aplicação web, em grande parte, dependem de métodos (ou funções) de uma aplicação externa para satisfazerem aos requisitos para o qual foram projetadas, e tais métodos estão hospedados em outros servidores, são aplicações de terceiros. 

Com isso, a aplicação e os métodos que complementam suas funcionalidades precisam se comunicar, e o padrão de arquitetura REST, adotado em interfaces de comunicação (aqui APIs) é implementado para que isso aconteça.

           Começando do começo: O que é REST e API

Imagine que você vai fazer uma viagem e solicita a reserva de um hotel em uma agência de viagens.

A agência tem seu sistema próprio, onde ao inserir um local, são listados alguns hotéis que podem ser ordenados de acordo com a classificação e proximidade do local da viagem, por exemplo. Isso é possível porque o sistema da agência se comunica com um serviço de outro sistema que provê esses dados.

Você escolhe o hotel onde quer ficar, e precisa fazer a reserva e checar a disponibilidade de datas. Novamente o sistema da agência fará uma comunicação com um serviço que disponibiliza esses dados, e baseados neles você decidirá quando será feita a reserva.

Por fim, ao efetuar a reserva, novamente o sistema da agência estabelece comunicação com outro sistema. Dessa vez, o do hotel escolhido, para confirmar as reservas.

Todas essas operações são feitas e providas graças ao uso de APIs.

           Ok, mas o que é uma API?

Como dito na introdução deste artigo, as aplicações precisam se comunicar, e as API (acrônimo de Application Programming Interface) é o canal por onde isso vai acontecer. Sua definição é um contrato que estabelece a comunicação entre duas aplicações, e como isso irá acontecer. Em outras palavras, é a forma como aplicações de diferentes origens e propriedades se conectam.

NA API, são apresentados padrões de uso, ferramentas, funcionalidades que vão ser usados na comunicação entre os sistemas. É essencial garantir a segurança dos dados trafegados implementando protocolos de criptografia, como o SSL, que vai controlar o que é trafegado e quem tem permissão para manipular os dados. Além do uso de criptografia, deve-se garantir que os dados sensíveis só serão acessados por aqueles a quem pertencem. Dessa forma, adota-se tokens para autenticação.

               Portanto, o uso de uma API deve proporcionar confiabilidade e segurança antes de pensar em outros pontos como escalabilidade e flexibilidade.

           Certo, já entendi sobre API. Mas está faltando falar do REST

REST (acrônimo para representational state transfer, traduzido como transferência de estado representacional) é um modelo de arquitetura que apresenta restrições de design para o seu uso. Possui as características:

• Usa o protocolo HTTP para o tráfego de dados, e é onde as aplicações se comunicam na modalidade cliente-servidor e podem ser usados recursos como cache e cookies;
• Por utilizar o protocolo HTTP, tem acesso aos métodos GET, POST, PUT e DELETE, entre outros, que são ações a serem aplicadas aos dados enviados/recebidos. Tais métodos são definidos para uso nos cabeçalhos das requisições HTTP;
•  É stateless, não armazena qualquer estado (ou dado) da comunicação entre as partes, além de as solicitações serem independentes e desconectadas entre si;
• Tem endpoints ou caminhos bem definidos. Ex.: no endereço http://www.hotelxyz.com.br/reserva , /reserva é um endpoint, ou URI, que identifica o recurso acessado;
• Fornece respostas semânticas e auto explicativas, através dos códigos de status de resposta HTTP (para saber mais sobre essas respostas, consulte HTTP response status codes - HTTP | MDN (mozilla.org)
• Permite o uso de HATEOAS, que é um tipo de mapa que permite ao usuário entender os caminhos da API, e navegar por eles.;
• Permite o uso de sistemas em camadas: o que permite o uso de balanceamento de cargas, cache compartilhado, tornando a aplicação escalável mais facilmente;
• A representação dos dados obedece a uma linguagem padrão. Hoje, a linguagem JSON (JavaScrit Object Notation) é predominante nas aplicações.

Do REST nasce a API RESTFul

Quando uma API obedece às restrições citadas acima, ela é considerada uma API RESTFul, em que o conceito REST foi aplicado em sua totalidade. Mas além disso, é importante que uma API RESTFul atenda também às seguintes restrições:

• Enviar recursos com estado muito bem definido, o que quer dizer detalhar e descrever ao máximo os dados a serem enviados:
• Seja documentada de forma clara e simples, detalhando cada funcionalidade da aplicação e os parâmetros necessários para usá-la;
• Os status de resposta de requisição devem ser usados semanticamente, ou seja, para a operação que estão especificados. Não é legal retornar um código 200 para uma requisição cuja resposta foi 403;
• Usar os métodos HTTP de forma semântica: em um estágio inicial, isso não é necessário, mas conforme a aplicação vai escalando, é importante usar a coerência para definir os métodos. Por exemplo: usar o método GET apenas para retornar uma requisição que solicita que sejam listados, POST para inserção de dados, e por aí vai;

Modelo REST e API Restful: qual a diferença?

O modelo REST é um conceito do padrão de arquitetura de sistemas, um conjunto de boas práticas. Já a API RESTFul é a implementação do padrão REST em uma API.

Numa analogia com a orientação a objetos, o REST seria como a classe, e API RESTFul o objeto instanciado dessa classe.

Prática de API RESTFul

Para ilustrar como é desenhada uma API RESTFul e seu funcionamento, será mostrado abaixo um fluxo de uma API que cadastra usuários e os lista.

Incluindo um usuário

Inicialmente, para garantir que o usuário que vai ser cadastrado não existe, é efetuada uma consulta de cadastro para checar se o usuário existe. Para isso, a aplicação usa o método GET, passando um JSON com as chaves “name” e “email”.

Perceba que foi retornado um objeto JSON contendo a chave “error”, com o valor “not found” e o status retornado foi o 400, que indica que o usuário não foi encontrado.

Certificando que o usuário não foi encontrado, uma requisição do tipo POST será enviada para cadastrá-lo.

Dessa vez foi retornado um objeto JSON, contendo os dados cadastrados, e o status da resposta da requisição foi o 201, indicando que tudo correu bem.

Mas, supondo que acidentalmente, a inserção do mesmo usuário seja solicitada, o que irá acontecer? Vamos conferir?

Novamente será retornado um objeto JSON, mas contendo apenas a chave “error”, descrevendo o que aconteceu, e o status da requisição foi novamente o 400 .

Consultando usuários cadastrados

É retornado um objeto JSON, contendo todos os usuários cadastrados, e o status da resposta é o 200, indicando que correu tudo bem.

Alguns exemplos de API RESTFul para explorar e praticar

A seguir, alguns exemplos de APIs simples, mas muito bem documentadas:

• SWAPI: SWAPI - The Star Wars API – API que retorna informações do universo Star Wars.
• APIs do IMDB: IMDb API Documentation - IMDb API (imdb-api.com) – Um compilado de várias APIs que trazem, por exemplo, listas do TOP 250 filmes e TOP 250 series conforme avaliações da plataforma. Necessário registro para que a plataforma libere o acesso.
• API Game of Thrones: An API of Ice And Fire – Traz informações do Universo de Game Of Thrones

Contribuição de Matheus Battisti (Activity | Matheus Battisti | LinkedIn)

Fontes

REST: REST - Glossário do MDN Web Docs: Definições de termos relacionados à Web | MDN (mozilla.org)

O que é API REST: O que é API REST? (redhat.com)

API – Dicionário do programador: https://youtu.be/vGuqKIRWosk visto em 13/07/2023.

REST – Dicionário do programador: https://youtu.be/S7MduKwvVGk , visto em 12/07/2023

O que é uma API RESTFul na prática: https://youtu.be/P92SBaN42mQ – visto em 12/07/2023.