REST
🧩

REST

Created
Nov 22, 2021 10:29 AM
Language
Português
Summary
Standards on good REST applications.
Attention Status
REST is non-opinionated, so you can do anything as long as your system is consistent and resource oriented.

Múltiplos Endpoints para Consultar um mesmo Recurso

Disponibilizar um mesmo recurso em múltiplos paths, não é um problema, contanto que o path faça sentido. E.g. /v1/customers/messages, /v1/messages, /v1/networks/3/customers/messages

Path Variables

Localização. Utilizados para identificar um recurso.
Bom uso:
  • /messages/{messageId} indica o identificador da mensagem dentro da coleção de mensagens.
  • /messages/102/briefing, quando briefing é um atributo do recurso de mensagem.
  • /mandatory/messages
Mal uso:
  • /messages/102/mandatory, quando mandatories é uma qualidade da mensagem utilizada para filtrar o que será retornado.
  • /messages/123/briefing, quando briefing não é um atributo do recurso mensagem, mas sim uma forma de determinar um conjunto de atributos que vão ser retornados.

Query Params

Filtragem e modificação. Devem ser utilizados para manipular o conteúdo retornado do recurso especificado no path. Isso significa que nada que identifique o recurso deve ser enviado via Query Param.
Bom uso:
  • /messages?forMandatoriesListing=true, o argumento forMandatoriesListing indica que será feito um filtro nas mensagens para retornar apenas as mensagens que se enquadrem nele.
  • /messages?page=1&limit=20, utilizado para paginação.
  • /messages?recipientId=123, é um filtro sobre um valor do recurso, não um identificador do recurso.
  • /customers/123/messages?view=summary, utilizado para definir o conjunto de dados que serão retornados do recurso.
Mal uso:
  • /messages?messageId=123, um identificador de recurso deveria ser Path Variable.
  • /messages/123?fields=recipients, quando identifica campos que serão retornados.

Bibliografia