APIs REST - Dicas básicas e boas práticas - II

Hoje vamos continuar a apresentação de dicas básicas e das principais boas práticas que podemos usar para criar e usar APIs Restful, ou seja, aderentes ao estilo REST.

Continuando a primeira parte do artigo veremos agora algumas dicas de boas práticas para as API Restful.

A formatação da URI

As APIs REST usam URIs (Uniform Resource Identifiers) para endereçar recursos.

Pode parecer um detalhe pequeno mas a formatação da URI pode comunicar de forma clara o modelo de recursos da API, como por exemplo http://macoratti.net/api/agatha-christie/morte-no-nilo, ou pode ser muito difícil de decifrar como http://macoratti.net/api/68dd0-a9d3-11e0-9f1c-0800200c9a66.

Ao criar uma API REST devemos transmitir o modelo de recurso da API aos seus consumidores de forma clara e suscinta.

Como formatar os endpoints nas URIs ?

Aqui a primeira dica é não usar verbos nas URIs.

Porque não ??

Simplesmente porque os verbos HTTP devem ser suficientes para descrever a ação que está sendo executada no recurso.

Veja os endpoints definidos a seguir :

/getAllProducts
/getAllProducts
/updateProduct/12
/deleteProduct/12
/getProductById/3
/deleteClient/3
/updateCliente/3

Temos aqui um monte de endpoints cada um realizando uma tarefa e isso pode ficar ainda mais confuso.

A solução é tratar cada recurso usando um substantivo e o método HTTP como um verbo. Isso simplifica a sintaxe e é tudo que você precisa para realizar as mesmas tarefas:

- GET /products – retorna todos os produtos
- GET /products/8 – retorna o produto com id igual a 8
- POST /products – inclui um novo produto e retorna os detalhes
- DELETE /products/7 – remove o produto com id igual a 7
- GET /clients/5/orders – retorna todos os pedidos do cliente com id igual a 5

Mais simples, mais fácil de entender e mais preciso.

Mas devo usar os nomes dos recursos no singular ou no plural ?

GET product/2/  ou GET products/2

Aqui não existe uma regra rígida mas creio que usar os nomes no plural reflete melhor o fato de que podemos ter muitos endpoints.

Assim creio que para agradar a todos vale a seguinte regra: 'Seja consistente com a escolha que você fez'

Se usar os nomes no singular faça isso em toda a sua API:

GET product/2

GET product

POST product

Além disso devemos usar a barra invertida (/) para indicar uma relacionamento hierárquico entre os recursos. Exemplo: http://api.desenho/formas/poligonos/quadrilateros/quadrados

Os hífens (-) devem ser usados para melhorar a legibilidade dos URIs, melhornado a legibilidade dos nomes nos segumentos de caminho longo.  Exemplo: http://api.exemplo.com/blogs/macoratti/posts/meu-primeiro-post

Já o sublinhado ( _ ) deve ser evitado pois dependendo da fonte usada o caractere sublinhado pode ficar oculto ou difícil de interpretar.

Quando conveniente, letras minúsculas são preferidas nos caminhos de URI, pois as letras maiúsculas às vezes podem causar problemas. A RFC 3986 define as URIs como diferenciando as maiúsculas das minúsculas, exceto os componentes do esquema e do host.

E para concluir não devemos incluir extensões de arquivos na URIs, visto que na web o caractere ponto é usado para separar as partes do nome do arquivo e da extensão de uma URI. Assim o tipo de mídia é informado no header Content-Type e não precisamos informar a extensão de um arquivo.

Retornar os detalhes dos erros no response body

Quando um servidor de API lida com um erro, é conveniente e recomendado retornar os detalhes do erro no corpo JSON para ajudar os usuários da API na depuração.

E quanto mais detalhes você incluir melhor, assim indicar quais campos foram afetados pelo erro é uma grande melhoria na sua API.

{
  "error": "Dados inválidos ao atualizar o  produto.",
  "detail": {
    "description": "Este campo deve ser informado."
  }
}

Preste atenção ao Status Code

Ao projetar e criar uma API Restful, fazemos a comunicação com o usuário da API usando códigos de status HTTP (status code), e, existem muitos códigos de status, descrevendo várias respostas possíveis.

Mas quantos deles devemos usar ?

Deveríamos ter um código de status estrito para todas as situações ?

Existem mais de 50 códigos de status definidos, e, aposto que você não conhece todos de cor.

Você acha que o usuário vai conhecer todos os código de status de erro ?

A maioria dos desenvolvedores está familiarizada com os códigos de status mais comuns como:

Ao começar com esses três, você já esta quase cobrindo a maioria das funcionalidades da sua API REST.

Outros códigos mais usados são:

O importante e retornar o código de status significativo que descreva corretamente o tipo de erro mesmo que você já tenha incluído os detalhes de erro no body do response.

Assim se sua API faz um POST e faltou a informação de um campo a resposta não pode ser 200 OK , seria melhor um 400 Bad Request.

Outro ponto importante é usar os status code de forma consistente.

Por exemplo, se você escolher que um endpoint POST retorne 201 Created em algum lugar, use o mesmo código de status para todos os endpoint POST

Por quê ?

Porque os usuários não precisam se preocupar qual método e em qual endpoint vai retornar qual código de status em qual circunstâncias.

Portanto, seja consistente e, se você se afastar das convenções, documente isso em algum lugar de forma clara.

Até o próximo artigo.

"(Disse Jesus) Ainda um pouco, e o mundo não me verá mais, mas vós me vereis; porque eu vivo, e vós vivereis."
João 14:19

Referências:

José Carlos Macoratti