A TAL DA API REST

30/04/2023

Primeiro vamos entender o que é uma API, a sigla significa Application Programming Interface, em tradução livre, Interface de Programação de Aplicações. Também podemos entender como se fosse um conjunto de rotinas de uma aplicação que possibilita que ela seja utilizada por outras aplicações sem que estas precisem conhecer profundamente seu código.

Como no exemplo acima em que temos as personagens, Cliente, Garçom e a Chefe da cozinha. O Cliente faz um pedido ao Garçom contendo todas as informações referente ao pedido, o Garçom por sua vez leva o pedido à cozinha e verifica com a Chefe se é possível fazer o pedido, se estiver tudo certo com o pedido, não faltar nenhum ingrediente, o pedido é executado e mandado ao Cliente. Mas caso não seja possível executar o pedido por falta de algum ingrediente, o Garçom retorna ao Cliente com a notícia que ele deve escolher outra coisa. Através deste exemplo simplificado podemos entender que uma API permite a comunicação entre aplicações e usuários.

E O REST ?

Agora que entendemos o conceito de API, vamos entender esse tal de REST. A sigla significa Representational State Transfer ou Transferência de Estado Representacional, em tradução livre. A ideia central do REST é possibilitar que um recurso, como um documento, seja transferido por meio de interações entre cliente-servidor bem padronizadas e independente de uma linguagem.

Importante entender que…

REST não é um protocolo ou padrão e sim um conjunto de regras que abstraem a arquitetura da web, permitindo a comunicação entre aplicações.

Requisições

A requisição que o cliente faz ao servidor possui a seguinte estrutura:

Header: Consiste no cabeçalho com as informações necessárias para a requisição, algumas requisições necessitam de tokens de autorização, por exemplo, este pode ser passado no Header da requisição.

Rota ou Endpoint: A url da requisição, ela pode aceitar parâmetros, como por exemplo um id para especificar um objeto de retorno.

Corpo: Dependendo da requisição e como foi construída a API, este elemento recebe informações necessárias para a requisição, em formato JSON.

Método HTTP: Define o tipo de operação que será realizada, as principais são:

GET: é utilizado para solicitar ao servidor que envie um recurso, não usa body e os parâmetros podem ser passados na própria URL.
POST: Utilizado para enviar dados de entradas para o servidor, a submissão de um formulário preenchido em um site, por exemplo, é feita utilizando o método POST. Neste caso os dados do formulário compõem o corpo da requisição.
PUT: Este método é utilizado para editar e atualizar documentos em um servidor.
DELETE: Remove os dados do servidor.

Na imagem conseguimos visualizar um exemplo de requisição. O campo destacado em vermelho mostra o método que está sendo utilizado. O campo verde contém a rota da requisição e nele temos duas informações: a url da chamada (amarelo) e o parâmetro necessário para identificar um personagem específico (roxo). Por fim, o campo azul contém as informações de cabeçalho da requisição.

A chamada em questão é de uma API pública que retorna informações sobre personagens de Os Simpsons.

Respostas

Toda requisição leva a uma resposta, basta lembrar do exemplo do restaurante. Se está tudo certo a Cozinha dá o OK ao Garçom que avisa ao Cliente que o pedido está sendo feito, se faltar algum ingrediente a Cozinha avisa ao Garçom que informa ao Cliente que ele precisará mudar o pedido.

A imagem acima mostra a resposta da chamada mostrada no exemplo anterior. O campo azul retorna o corpo da resposta com as informações disponíveis pela API refente ao ID 72, informado no fim da URL da requisição. O campo branco indica o tempo que a requisição levou para ser executada e o tamanho do arquivo gerado. E por fim, o campo verde retorna o código que indica o status da requisição, no exemplo é retornado o código 200, que significa que a requisição foi atendida com sucesso.

Os principais códigos de resposta, além do 200 (OK) são: