REST: Boas práticas 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.