Category Archives: REST

REST – Boas Práticas

REST No Comments

Este post visa apresentar as boas práticas na implementação de serviços REST.

REST – Conceito

REST (Representational State Transfer) é um modelo arquitetural que foi apresentado em uma tese de doutorado de Roy Fielding, 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. Mais adiante, veremos exemplos de RESTful.

Nomenclatura de URIs

Para facilitar o uso de sua aplicação REST, é bom utilizar versionamento na URI (também conhecido como endpoint).

Exemplo:

  • http://[DOMINIO]/api/v1 (URI sem contexto e subdomínio)
  • http://[SUBDOMINIO].[DOMINIO]/api/v1 (URI sem contexto e com subdomínio)
  • http://[DOMINIO]/[CONTEXTO/api/v1 (URI com contexto e sem subdominio)
  • http://[SUBDOMINIO].[DOMINIO]/[CONTEXTO]/api/v1 (URI com contexto e com subdomínio)

Recursos da URI

Após a definição de Subdomínio, Contexto e Versão, definimos os recursos de nossa API, geralmente, utilizando identificadores no plural.

Exemplo:

  • /customers
  • /products
  • /invoices

Métodos HTTP

É boa prática utilizar métodos HTTP para identificar as operações permitidas.

Exemplo:

  • 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.

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

Excluir o documento de id 1

[DELETE] /documents/1

Resposta HTTP

Ao invocar um método, o cliente precisa receber uma resposta sobre a execução do método, se ocorreu tudo bem ou se apresentou erro. Para ajudar a identificar o erro, a API deve utilizar o código HTTP da maneira mais usual de mercado.

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.

A lista completa de Código HTTP pode ser consultada em https://httpstatuses.com

Filtragem(Filtering)

Para filtrar o conjunto de dados, podemos passar várias opções por meio de parâmetros de consulta.
Por exemplo, GET /pessoas?tipo=pf&localizacao=SC filtraria os dados da lista de pessoas físicas de Santa Catarina.

Pesquisa(Searching)

Ao pesquisar o nome da pessoa na lista de pessoas, o endpoint a ser exporto deve ser do tipo GET = /pessoas?Search=fernando

Paginação(Pagination)

Quando o conjunto de dados é muito grande, dividimos o conjunto de dados em partes menores, o que ajuda a melhorar o desempenho e é mais fácil de lidar com a resposta(controlar itens por página e quantas páginas podem ser mostradas).
Por exemplo: GET /pessoas?Page=23 significa obter a lista de pessoas da 23ª página.
Se adicionar muitos parâmetros de consulta em métodos GET tornar o URI muito longo, o servidor poderá responder com 414 URI Status HTTP muito longo. Nesses casos, params também podem ser passados no corpo da solicitação do método POST.

RESTful

Uma API RESTful significa que ela possui a capacidade de evoluir e ajudar a identificação de métodos relacionados. Por exemplo, no método de consulta de um pedido, podemos incluir no retorno, a URI para consultar os dados do Cliente, facilitando a codificação das aplicação que usam a API.

Exemplo (veja o atributo permalink):

{
   "invoiceNumber": 21564879821,
   "invoiceDate": "2012-10-09 12:00:00 +05:30",
   "customer": {
      "document": "01698798166215",
      "name": "John Baker",
      "permalink": "/v2/customers/3a22b041-8d45-496a-946d-bd2252a0d28c"
   }
}