Desmistificando API Rest
Tags: javascript, api, node, iniciantes
Published: 2020-03-10 14:25:28


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: <a target="_blank" href="https://amzn.to/3onayIz">Construindo Aplicações com NodeJS</a><img src="//ir-br.amazon-adsystem.com/e/ir?t=blogmonica-20&l=am2&o=33&a=8575226851" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />
Livro: <a target="_blank" href="http://amzn.to/2NCKVqx">Node Essencial</a><img src="//ir-br.amazon-adsystem.com/e/ir?t=blogmonica-20&l=am2&o=33&a=8575226770" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />
Livro: <a target="_blank" href="https://amzn.to/3a5Bmbk">Programação web com Node e Express</a>

Postado originalmente em: <a href="https://monicavasconcelos.net" target="_blank">Blog Pessoal</a>