Índice

...

• Definir práticas e padrões consistentes para todos os endpoints das APIs da TOTVS;
• Garantir a utilização mais próxima possível das boas práticas estipuladas pelos padrões REST/HTTP;
• Tornar os serviços da TOTVS acessíveis através de APIs facilmente compreendidas e documentadas para desenvolvedores e consumidores.
  
  

...

Cada um dos membros deve obrigatoriamente ser incluído no pull request de novas APIs publicas e cada um deles é responsável por garantir a correta disseminação e implementação dentro de seu próprio time das APIs privadas.

Estrutura de URLs

Como regra geral seguimos os passos abaixo sempre que precisarmos criar um novo recurso:

...

Exemplo de filtros no padrão odata:

Filtros de data Modificação (opcional)

...

Na tabela abaixo serão listados os métodos que devem ser suportados. Nem todos os endpoints devem suportar todos os métodos, mas os que o fizerem devem respeitar a utilização conforme descrita.

PUT http://totvs.com/api/users/10

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

PATCH http://totvs.com/api/fluig/fdn/v1/users/10

[
  { "op": "replace", "path": "/name", "value": "Bob" }
]

Corpo de mensagem e Query String

...

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://totvs.com/api/fluig/fdn/v1/users
{
 ...
}

202 Accepted
Location: https://totvs.com/api/fluig/fdn/v1/queue/10

Como escolher o método adequado

...

A utilização destes cabeçalhos não é obrigatória para todos os endpoints, mas os que os utilizarem devem obedecer as regras descritas abaixo.

Padrões de cabeçalhos de respostas

Endpoints devem retornar estes cabeçalhos em todas as repostas, a menos que explicitamente citado o contrário na coluna obrigatório.

Cabeçalhos customizados

Cabeçalhos customizados não devem ser utilizados para representar qualquer estado, valor ou ação sobre a entidade representada pela url. Isso quer dizer que cabeçalhos não devem ter relação com o cliente do endpoint (mobile, desktop, etc), url, corpo da mensagem, corpo da resposta ou parâmetros da url. O protocolo HTTP oferece uma série de cabeçalhos para quase todas as situações e estas sempre tem precedência a um cabeçalho customizado.

...

A deleção do recurso temporário não é obrigatória e PODE ser feita através de DELETE do client, ou através do próprio server, após um tempo determinado para expirá-lo. Nesse segundo caso, ao tentar acessá-lo DEVE retornar 410 (Gone).

Padrão HATEOAS

...

Esse estilo de arquitetura permite usar links no conteúdo da resposta para que o cliente possa navegar dinamicamente para o recurso apropriado. Isso é conceitualmente o mesmo que um usuário da Web navegando pelas páginas e clicando nos hiperlinks apropriados para atingir uma meta final.

...

Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação. Além disso deve ser gerado um documento OpenAPI com as definições da API.{  
   "id":10,
   "name":"Usuário",
   "age":25,
   "links":[  
      {  
         "rel":"communities",
         "href":"/fdn/v1/communities/5"
      },
      {  
         "rel":"permissions",
         "href":"/fdn/v1/permissions/30"
      }
   ]
}