Desmistificando API Rest

18 de novembro de 2020 Atualizado em: 28 de janeiro de 2021
DesenvolvimentoNodeJavascriptApi

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, utilizando 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.

1form 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.

1Ex. /livros?lingua=pt-br.

Recurso – É um caminho. Ex. 

1http://site.com.br/carros
 (a palavra carros é o recurso).

Parâmetros – São variáveis enviadas na URI. Ex. 

1http://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:

1/projetos – lista todos os projetos
1/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:

1/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:

1/projeto/all

O melhor seria:

1/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:

1/projects?name=”TESTE” em vez de /getProjectsByName
1/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.

1/v1/projects
1/v2/projects

É importante evitar algo do tipo:

1/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:

1/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:

Bloghttps://blog.caelum.com.br/rest-principios-e-boas-praticas/

Bloghttps://medium.com/better-programming/restful-api-design-step-by-step-guide-2f2c9f9fcdbf

Bloghttp://bluedev.com.br/2017/10/23/conceito-de-apis/

Recomendação de leitura:

Livro: Construindo aplicações com Node

Livro: Node essencial

Livro: Programação web com Node e Express

Monica Vasconcelos
Monica Vasconcelos
FullStack Developer & UI Designer

Desenvolvedora de software com graduação em Análise de Sistemas e pós-graduação em Engenharia de Software, atuo na área de desenvolvimento web, especialmente com UX/UI design e programação utilizando as tecnologias: React, Typescript, Node, Django, Postgres, MySql e Wordpress.

Comentários
logo branca
Desenvolvedora de software com graduação em Análise de Sistemas e pós-graduação em Engenharia de Software, atuo na área de desenvolvimento web, especialmente com UX/UI design e programação utilizando as tecnologias: React, Typescript, Node, Django, Postgres, MySql e Wordpress.
Redes Sociais e Email
email: contato@monicavasconcelos.dev
11 9320 73087
Copyright@2021 - Todos os diretos reservados