Desmistificando API Rest

API é uma interface que expomos ao mundo. Tem o principal objetivo de disponibilizar recursos de uma aplicação para ser consumida por outra aplicação. É construída por um elemento de especificação que descreve como a informação é trocada.
Desta forma, entendemos que as APIs permitem uma interoperabilidade entre aplicações, ou seja, a comunicação entre aplicações e entre os usuários.

REST
REST é um acrônimo de Representational State Transfer, e tem como objetivo primário a definição de características fundamentais para a construção de aplicações Web seguindo boas práticas.
Não é um padrão e sim uma arquitetura. Os formatos suportados são JSON e XML e utiliza apenas o protocolo HTTP/HTTPS. As requisições são feitas com GET, POST e até outros métodos menos conhecidos do protocolo HTTP, como PUT e DELETE. Porém, o HTML só implementa dois verbos: GET e POST. Para que consigamos utilizar os demais, podemos enviar na query string do action do formulário o método que queremos utilizar. O servidor que receber a requisição deverá entender isso.

form action=”/planets?_method=DELETE” method=”POST”

Toda aplicação que gerencia informações é chamada de recurso no modelo REST. Um recurso é uma abstração de um determinado tipo de informação que uma aplicação gerencia e deve possuir uma identificação única. Essa identificação é utilizada para diferenciar qual recurso será manipulado em uma determinada solicitação. A identificação do recurso deve ser feita utilizando-se o conceito de URI (Uniform Resource Identifier).

API Restful é, portanto, uma API (Application programming interface) que utiliza requisições HTTP para coletar, inserir, postar e deletar dados, tendo como base a arquitetura REST muito utilizada no desenvolvimento de serviços web, baseada nos conceitos do protocolo HTTP.

CARACTERÍSTICAS DO REST

• Cada requisição ao serviço deve retornar o conteúdo sem manter estado, ou seja, uma requisição é independente da outra.
• Tem um conjunto de operações padronizadas
• Utiliza uma URI (Uniform Resource Identifier), ou, uma sintaxe universal para identificar recursos.
• Utilização de tipos de conteúdo (mime-type) para solicitar e retornar conteúdo, com isso é possível que o cliente especifique se deseja que o conteúdo seja retornado em XML ou JSON, por exemplo.

Vejamos abaixo como funciona a estrutura da requisição e resposta:

Estrutura da requisição
Uma requisição é um pedido que fazemos a um webservice. O protocolo HTTP é baseado em pedidos e respostas. Quando um navegador acessa um site, ele envia uma requisição ao servidor, pedindo o conteúdo. Esse conteúdo que vem em forma de HTML é a resposta do servidor.

Veja a estrutura:
Endpoint – É o endereço web.
Query – É a query string na URI. Ex. /livros?lingua=pt-br
Recurso – É um caminho. Ex. http://site.com.br/carros (a palavra carros é o recurso).
Parâmetros – São variáveis enviadas na URI. Ex. http://site.com.br/carros/1 (o número 1 é o parâmetro).
Cabeçalho – São dados adicionais enviados na requisição. Ex. tipo de mídia que aceitamos como retorno, token para autenticação etc.
Método – É o tipo de requisição, chamado também de verbo. Ex. OPTIONS, GET, HEAD, POST, PUT, DELETE.
Dado – É o corpo da requisição. Ex. quando enviamos um formulário via POST, os dados nos inputs são o corpo da requisição.

Estrutura da resposta
A resposta é o retorno, que é o resultado de uma requisição.

Veja a estrutura:
Status Code – É uma representação numérica de resposta. Veremos detalhes mais a frente.
Dado – É o corpo do retorno. O resultado da requisição.
Cabeçalho – São informações extras enviadas pelo servidor.

PRINCÍPIOS PARA DESENHAR APIs RESTFUL

Veremos agora como entender os principais princípios que devemos seguir para desenhar APIs.

- Mantenha simples
A base da URL deve ser simples e intuitiva. Por exemplo, se queremos desenhar APIs para projetos, poderemos fazer algo parecido como:

/projetos – lista todos os projetos
/projetos/123 – lista um projeto específico

- Use nomes, não verbos
Um dos grandes erros ao criar APIs está relacionado aos endpoints. O padrão Restful exige que sejam utilizados nomes e não verbos. Por exemplo, para exibir todos os projetos, devemos usar:

/projetos e não /obterProjetos

- Use o método HTTP certo
GET – Obter um recurso ou uma coleção de recursos. Método mais comum de requisição. Deve ser utilizado para serviços de consultas. Possui limite de caracteres, 2045, que varia conforme o browser, por isso é boa prática passar poucos caracteres na URL. Sempre que um endereço de uma página é digitado no browser, uma requisição GET é feita.
POST - Criar um recurso ou uma coleção de recursos. É utilizado para enviar dados ao servidor, por exemplo: cadastro de usuários, cadastro de login, upload de fotos, etc
PUT/PATCH – Atualizar um recurso existente ou uma coleção de recursos. Sua requisição é parecida com POST.
DELETE – Deletar um recurso existente ou uma coleção de recursos. Sua requisição é parecida com GET.

- Use Plural
É importante manter no plural, para evitar confusão sobre se estamos falando de obter um único recurso ou uma coleção de recursos. Também evitar adicionar informações adicionais na URL, como:

/projeto/all

O melhor seria:

/projetos

- Use Parâmetros
Às vezes precisamos de uma API que passe mais informações do que apenas uma identificação. Nesses casos, devemos usar parâmetros de consulta, por exemplo:

/projects?name=”TESTE” em vez de /getProjectsByName
/projcts?type=”xyz” em ez de /getProjectsByType

Dessa forma você evita URLs longas com simplicidade.

- Use os códigos HTTP corretos
Sempre que uma requisição HTTP é feita, um código numérico é retornado, indicando o resultado da requisição.
Esses códigos são divididos em cinco famílias:
1xx – Informacionais
2xx – Códigos de sucesso
3xx – Códigos de redirecionamento
4xx – Erros causados pelo cliente
5xx – Erros originados no servidor

Existem diversos tipos de código HTTP, mas vou tratar aqui apenas dos mais comumente utilizados:

200 OK – Usado para mostrar que a requisição foi bem sucedida.
201 CREATED – Usado quando se usa o método POST para criar novo recurso e indica que o recurso foi salvo com sucesso.
202 ACCEPTED - Usado para confirmar a solicitação enviada ao servidor e que será processada em outro momento. Usado tipicamente em requisições assíncronas, que não serão processadas em tempo real.
204 NO CONTENT – Requisição efetuada com sucesso, porém não existe nenhum retorno.
301 – MOVED PERMANENTLY – Requisição com sucesso, mas fez um redirecionamento para outra página.
400 BAD REQUEST – Usado quando da validação de entrada do lado do cliente falha. Requisição inválida.
401 UNAUTHORIZED - Indica falha na autenticação do serviço ou que se a autenticação ainda não feita.
403 FORBIDDEN – Indica que o acesso a essa página foi negado por questões de segurança.
404 NOT FOUND – Usado quando se está procurando um determinado recurso e ele não está disponível no sistema.
405 – METHOD NOT ALLOWED – Caso o método HTTP solicitado não puder ser encontrado na página. Por exemplo, se o cliente tiver solicitado uma requisição do tipo DELET, mas o web service não a suportar.
500 – INTERNAL SERVER ERROR – Não usado explicitamente, mas pode ocorrer quando o sistema falhar.
502 BAD GATEWAY – Usado se o servidor, enquanto atuando como um servidor intermediário (gateway ou proxy), recebeu uma resposta inválida do servidor para o qual a requisição foi encaminhada..
504 – GATEWAY TIMEOUT – Erro de timeout caso a requisição não retorne no tempo estipulado.

Essa é uma lista resumida. Para a lista completa, recomendo a leitura abaixo:

https://en.wikipedia.orgwiki/List_of_HTTP_status_codes
https://www.w3.org/Protocols/HTTP/HTRESP.html

Versionamento
Versionamento de APIs é muito importante. Usado de diferentes maneiras: alguns desenvolvedores usam como data, enquanto outros usam versões como parâmetros de consulta.

/v1/projects
/v2/projects

É importante evitar algo do tipo:

/v1.2/projects

Pois isso implica que a API muda frequentemente. Mantenha as coisas simples. É sempre boa prática manter a compatibilidade com as versões anteriores.

- Use paginação
O uso de paginação é obrigatório quando você expõe uma API que pode retornar grande volume de dados. Se não for feito corretamente o consumidor por desativar o serviço.
O uso de limite e deslocamento é recomendado aqui. Por exemplo:

/projects?limit=25&offset=50

Também é recomendável manter um limite e deslocamento padrão.

- Formatos suportados
É muito importante escolher como sua API responde. As aplicações modernas utilizam JSON, a menos que você tenha uma aplicação que precise obter uma resposta XML.

- Use mensagens de erro adequadas
É sempre uma boa prática manter um conjunto de mensagens de erro que a aplicação envia e responde com a identificação adequada.

Se você chegou até aqui, aprendeu os principais conceitos e as principais características de uma API Rest, no entanto deve ter notado que o tema é complexo e não é minha intenção esgotá-lo em um único artigo. Nos próximos artigos você verá como implementar uma API simples utilizando NodeJs.

Se gostou do artigo, curta e compartilhe.

Sugestões de melhoria são muito bem vindas.

Até a próxima.

Referências:

Blog: http://bluedev.com.br/2017/10/23/conceito-de-apis/
Blog: https://blog.caelum.com.br/rest-principios-e-boas-praticas/
Blog: https://medium.com/better-programming/restful-api-design-step-by-step-guide-2f2c9f9fcdbf

Recomendação de leitura:

Livro: Construindo Aplicações com NodeJS
Livro: Node Essencial
Livro: Programação web com Node e Express

Postado originalmente em: Blog Pessoal