Tecnologia

REST: Boas práticas para desenvolvimento de APIs

Por Vitor Precioso

17 outubro 2018 - 15:37 | Atualizado em 25 janeiro 2023 - 23:51


rest-boas-praticas-para-desenvolvimento-de-apis

REST (Representational State Transfer) é um modelo arquitetural que foi apresentado em uma tese de doutorado de Roy Fielding, que também é co-autor do protocolo HTTP.

RESTful, existe uma confusão entre os dois termos REST e RESTful, resumidamente REST é o modelo arquitetural e RESTful é um sistema que é capaz de aplicar integralmente os princípios de REST.

Termos utilizados

Recurso: É tudo aquilo que uma API pode gerenciar e manipular dados realizando operações como cadastrar, ler, alterar, remover. Documentos, funcionários e empresas são exemplos de recursos de uma API.

Cliente: É o responsável por realizar as requisições ao servidor utilizando a API.

Servidor: Recebe as requisições e as processa retornando uma resposta de sucesso ou falha.

Nomenclatura das URIs

URI (Uniform Resource Identifier) – o identificador deve ser único e preferencialmente que tenha o nome do recurso para facilitar a sua utilização.

Ex: Para os recursos documentos , funcionários e empresas nada melhor que:

  • /documents
  • /employees
  • /companies

É recomendado também que mantenha consistência não é interessante que seu endpoint utilize nomenclatura de recursos no plural e singular ao mesmo tempo.

Ex: /document

/documents

O ideal é que caso queira buscar um recurso específico utilize o seu id.

Ex: /documents/1

Retorna o documento de id 1.

Não utilize nome da ação nas URIs, pois assim não é possível a sua reutilização.

Exemplos de como NÃO fazer:

/registerDocument

/deleteDocument

/alterDocument

/searchDocument

Para informar a ação desejada nada melhor que utilizar os verbos HTTP.

Os métodos HTTP mais utilizados são:

GET solicita dados do recurso. Requisições utilizando o Método GET devem retornar apenas dados e não devem produzir nenhuma alteração na base.

POST solicita que o servidor crie um recurso no banco de dados.

PUT solicita que o servidor atualize o recurso.

DELETE solicita que os recursos, ou sua instância, sejam removidos do banco de dados.

PATCH solicita que o servidor realize modificações parciais em um recurso.

Portanto todas aquelas URIs podem ser substituídas por uma só, o próprio nome do recurso. E os verbos que ditam qual ação será realizada.

Cadastrar um documento

[POST]  /documents

Buscar todos os documentos

[GET] /documents

Buscar o documento de id 1

[GET] /documents/1

Alterar o documento de id 1

[PATCH] /documents/1

É recomendado utilizar PATCH ao invés de PUT quando a alteração for parcial, ou seja, quando nem todos os atributos serão alterados (o que acontece na maioria das vezes).

Deletar o documento de id

[DELETE ] /documents/1

Ao trabalhar com múltiplas entidades trabalhe o relacionamento entre elas desta forma:

[GET] /companies/1/employees/1

Assim fica muito mais fácil o entendimento. O retorno da requisição acima é o funcionário de id 1  da empresa de id 1.

E se houver a necessidade de retornar todos os funcionários da empresa de id 1 ?

Simplesmente utilize:

[GET] /companies/1/employees/

Códigos de status de resposta HTTP

Quando o cliente realizar uma requisição ao servidor, ele necessita de uma resposta para saber o resultado de sua solicitação, se ocorreu um erro, se tudo ocorreu bem ou se a solicitação estava errada.

Categorias:

2xx (Categoria de sucesso)

Esses códigos de status representam que a ação solicitada foi recebida e processada com sucesso pelo servidor.

200 OK

Código de resposta padrão representando sucesso para o  GET, PUT ou POST.

201 Created

Deve ser retornado sempre que uma nova instância for criada.

204 No Content

O servidor processa corretamente a requisição, mas não precisa retornar nenhum conteúdo.

4xx (Categoria de erros causados pelo cliente)

Esses códigos de status representam que solicitação realizada pelo cliente está incorreta.

400 Bad Request

Indica que a solicitação realizada pelo cliente não foi processada, pois o servidor não conseguiu entender o que o ele está solicitando.

401 Unauthorized

Indica que o cliente não tem permissão para acessar recursos e deve solicitar novamente com as credenciais necessárias.

403 Forbidden

Indica que a solicitação é válida e o cliente está autenticado, mas o cliente não tem permissão para acessar a página ou recurso por qualquer motivo. Por exemplo, às vezes, o cliente autorizado não tem permissão para acessar o recurso específico.

404 Not Found

Indica que o servidor não encontrou nada que corresponda à URI solicitada.

5xx (categoria de erro do servidor)

Categoria de erros gerados pelo servidor ao processar a solicitação.

500 Internal Server Error

Indica que a solicitação é válida, mas o servidor encontrou uma condição inesperada que impediu o cumprimento da solicitação.

503 Service Unavailable

Indica que o servidor está inoperante ou indisponível para receber e processar a solicitação. Principalmente se o servidor está em manutenção.

Comentários:

Uma resposta para “REST: Boas práticas para desenvolvimento de APIs”

  1. antonio fernando galdino de oliveira disse:

    achei muito interessante como trabalhamos como devemos trabalhar com as api’s pois assim depois de um tempo se precisarmos dar algum tipo de manutencao no codigo fica muito mais facil entender a logica utilizada e achar possiveis problemas e solucionarmos

    • Telefone - 35988654149

Deixe um comentário

O seu endereço de e-mail não será publicado.