...

Os caminhos definidos para cada endpoint devem ser de fácil leitura e significativos para o cliente para facilitar a sua descoberta e adoção. Os pontos abaixo DEVEM ser considerados ao criar uma URL:

• Ao referenciar uma entidade na URL ela DEVE estar no plural. Ex. /users ao invés de /user
• Evite caminhos com mais de 3 parâmetros pois isso dificulta a leitura e normalmente indica um problema arquitetural.
• O caminho DEVE apontar para um recurso e não para uma ação sobre a entidade, use os verbos HTTP para representar uma ação. Nos casos onde não exista um verbo apropriado a ação pode ser informada como parâmetro no caminho da url ou na url.

Exemplo de URLs amigáveis:

Descrever plural para entidades

 Colocar exemplo de filtro e expansiveis Evitar url com mais de 3 PATH param para não dificultar leituraexpansíveis

• Entidade apresentada no plural e uso correto do parâmetro na url.
  • https://fluig.totvs.com/api/users/{id}
• Ações sobre entidades no caminho da url e como parâmetro da url.
  • https://fluig.totvs.com/api/workflows/{id}?action=execute
  • https://fluig.totvs.com/api/workflows/{id}/send
• Relacionando entidades diretamente no caminho
  
  • https://fluig.totvs.com/api/users/{alias}/communities
  • https://fluig.totvs.com/api/communities/{id}/users
• URL com suporte a campos expansíveis (linkar para a sessão de campos expansíveis)
• https://fluig.totvs.com/api/users/{alias}?expand=prop1.subprop,prop2
  
  

Exemplo de URLS NÃOamigaveis e que deve ser evitadas:

• Redundância na definição da url
  • https://fluig.totvs.com/api/communty/listCommunities
• Ordenação especificada na url
  • https://fluig.totvs.com/api/communty/listCommunitiesWithRelevance
• Verbos definidos na url ao invés de usar o verbo HTTP e falta de pluralização no substantivo.
  
  • https://fluig.totvs.com/api/correlationquestion/create
  • https://fluig.totvs.com/api/user/create
  • https://fluig.totvs.com/api/user/delete
• Identificador da entidade definido como parâmetro e não como caminho (na url)
  • https://fluig.totvs.com/api/document/permissions?documentId={id}

No caso em que não existe um verbo adequado pode ser usado a "ação" na url. Desenha pra pessoas.

Apesar de o padrão definido no documento RFC 7230 da especificação do HTTP 1.1 não definir um tamanho maximo para a url nenhum endpoint do fluig deve ser identificado com uma url maior que 2000 caracteres para garantir que todos os navegares modernos sejam suportados

...

POST http://fluig.totvs.com/api/users/10

{
  name: "",
  age: 20,
  ...
}

POST http://fluig.totvs.com/api/users/10

{
  name: "Novo nome do usuário"
}

Post

Descrever as situações de 200 201 202

Operações do tipo POST assíncronas DEVEM retornar a localização de qualquer objeto criado que tenha um identificador.

...

POST x PUT x PATCH

Deve-se atentar aos códigos de retorno para os tipos de operações definidos para usar estes métodos principalmente nos casos definidos abaixo:

POST 

...

https://fluig.totvs.com/api/users

...

{
 ...
}

202 Accepted
Location: https://fluig.totvs.com/api/users/10

Onde 10 é o id do novo usuário criado.

...

Apesar de ambos atualizarem um objeto é importante notar que existe uma diferença na implementação destes métodos.

PUT DEVE ser considerado uma substituição total do objeto, ou seja, caso o cliente deixe de enviar uma propriedade para ser atualizada ela será considerada nula e poderá inadvertidamente remover valores do objeto.

PATH foi padronizado pelo IETF como o método usado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas.

Padrões de cabeçalhos de requisição

...

1. O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
2. O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage;