Sejam todos bem vindos! Nesse artigo vou falar sobre boas práticas arquiteturais de criação de uma API REST (Application Programing Interface).

Quando criamos uma API REST devemos manter um padrão arquitetural com boas práticas. Para não fazer mau uso dos códigos de status, as respostas enviadas por nosso servidor devem ser bem contextualizadas e possuir esquemas consistentes.

Noções básicas de métodos HTTP

Para construirmos uma boa API REST devemos conhecer os fundamentos do protocolo HTTP. Afinal, isso nos ajudará a fazer boas escolhas de design para a aplicação.

REST é orientada a recurso, ou seja, um recurso é representado por um URI: /users/ .

Os seis métodos HTTP mais utilizados nas aplicações são: GET, POST, PUT, PATCH e DELETE.

GET – LEITURA http://minhaapi.com/users
POST – CRIAÇÃO http://minhaapi.com/users
PUT – ATUALIZAÇÃO http://minhaapi.com/users/1
PATCH – ATUALIZAÇÃO PARCIAL http://minhaapi.com/users/1
DELETE – DELEÇÃO http://minhaapi.com/users/1

Use HTTP Codes de forma consistente

Não é possível retornar qualquer tipo de htttp code para o back-end, pois como um todo possui padronizações para atender os métodos htttp. Do contrário, seria bizarro se nossa API retornasse uma resposta de erro com status code 200 ok. Por isso vamos mapear os HTTP Codes e assim nunca esquecermos desse ponto primordial para uma API.

1xx – Respostas de informação

  • A solicitação foi aceita ou o processo continua em andamento.

2xx – Respostas de suscesso

  • 200: SUCCESS – Requisição bem sucedida
  • 201: CREATED: Usado geralmente para o método POST após uma inserção de dados

3xx – Redirecionamentos

  • 301: MOVED PERMANETLY. – Esse código de resposta significa que a URI do recurso requerido mudou
  • 302: FOUND. – Esse código de resposta significa que a URI do recurso requerido foi mudada temporariamente

4XX – Erros do Cliente

  • 400: BAD REQUEST
  • 401: UNAUTHORIZED – O usuário não forneceu credenciais de autenticação e as credencias são inválidas
  • 403: FORBIDEN – O usuário foi autenticado corretamente, mas não tem as permissões necessárias para acessar o recurso
  • 404: NOT FOUND
  • 422: UNPORCESSABLE ENTITY

5xx – Erros no servidor

O servidor falhou ao concluir a solicitação

  • 500: INTERNAL SERVER ERROR
  • 502: BAD GATEWAY

Use substantivos de recursos no plural

Sempre que criamos as rotas da aplicação é comum termos dúvidas sobre manter a rota no singular ou plural. Para evitar ambiguidade dentro do recurso que o cliente vai usar, recomendo utilizar a nomeação do substantivo de recurso no plural. Dessa forma, mantemos um padrão na nomenclatura de rotas e agregamos uma boa prática de criação de API REST.

Busca de to do list – GET http://minhaapi.com/todos
Busca de to do list por id – GET http://minhaapi.com/todos/1
Inserção de um novo to do – POST http://minhaapi.com/todos
Atualização de um to do – PUT http://minhaapi.com/todos/1
Atualização do status de um to do – PATCH http://minhaapi.com/todos/1
Deletar um to do – DELETE http://minhaapi.com/todos/1

Detalhar o erro na resposta para o servidor

Quando o backend tratar um erro, você deve retornar os detalhes do erro no corpo do JSON da aplicação. Dessa forma ajudamos a depurar a aplicação e achar o erro de forma mais rápida e eficaz.

{
"error": "User not found"
"detail": {
	"cpf": "cpf not found in the database"
	}
}

Um dos benefícios de uma API REST é que podemos atender múltiplos clientes (front-end), mantendo somente um backend, além de podermos fazer comunicação com outros serviços externos.

Espero ter ajudado você a compreender a criar uma API REST com boas práticas arquiteturais.

bons estudos!