...

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

...

Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio, criar um novo grupo de endpoints implica em preocupações como versionamento, disponibilidade e documentação. Usamos como base a estrutura "{protocolo}://{host}/{api}/{agrupador}/{dominio}/{versao}/{recurso}". Ex: https://fluig.totvs.com/api/ecm/sucuritysecurity/v1/users. A partir deste ponto deve-se considerar como regra básica a complexidade necessária para descobrir estes endpoints, ou seja, o agrupamento deve facilitar e não complicar a descoberta dos serviços.

...

Estrutura OAS (Open Api Specification 3.0.1):

openapi: 3.0.1
info:
  title: Estrutura de Url para API's
  description: 'Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio. Usamos como base a estrutura "{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}"'
  version: '1.0'
externalDocs:
  url: 'http://tdn.totvs.com/display/INT/Guia+de+implementacao+das+APIs+TOTVS'
servers:
  - url: '{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}'
    variables:
      protocolo:
        default: https
        enum:
          - http
          - https
      host:
        default: host
      api:
        default: api
      produto:
        default: produto
      agrupador:
        default: agrupador
      dominio:
        default: dominio
      versao:
        default: versao
      recurso:
        default: recurso
paths: {}
components: {}

...

GET http://totvs.com.br/api/fluig/fdn/v1/users/1

{
  name: "John",
  surname: "Doe"
}

...

Nos casos em que o resultado da operação do endpoint represente uma coleção, os itens devem estar agrupados em um objeto com as propriedades hasNext, indicando se existe uma próxima página com mais registros para aquela coleção e items que representam a lista de itens retornados.

{
  hasNext: true,
  items: [
    {},
    {},
    ...
  ]
}

A estrutura acima é a mínima esperada para respostas de coleção. Entretanto, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. Por exemplo:

{
  totvs_transaction_id: 1,
  total: 100,
  hasNext: true,
  items: [
    {},
    {},
    ...
  ]
}

Observe que na estrutura acima, os atributos totvs_transaction_id e total foram adicionados ao objeto de resposta, enquanto os atributos hasNext e items foram mantidos.

Mensagens de sucesso DELETE

Por padrão, nas mensagens de DELETE, a resposta deve ser enviada com HTTP Code 204 (No content) e sem corpo no retorno. 

Caso a regra de negócio necessitar de um retorno com conteúdo, este deve vir com HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.

...

Opcionalmente, o atributo _messages pode ser incluído no objeto retornado para fornecer alguma informação complementar ao processamento realizado (mensagens de aviso, de negócio, etc.). O formato do objeto de mensagem segue o padrão anteriormente descrito, para mensagens de erro.

GET http://totvs.com.br/api/fluig/fdn/v1/users/1

{
  name: "John",
  surname: "Doe",
  _messages: [{
	code: "INFO",
    message: "This is an informative message",
    detailedMessage: "Some details about this informative message can be found here!"
  }]
}

Âncora
ApiSuccessMsgColl ApiSuccessMsgColl

Mensagens de sucesso para coleções

Nos casos em que o resultado da operação do endpoint represente uma coleção, os itens devem estar agrupados em um objeto com as propriedades hasNext, indicando se existe uma próxima página com mais registros para aquela coleção e items que representam a lista de itens retornados.

{
  hasNext: true,
  items: [
    {},
    {},
    ...
  ]
}

Para o retorno de coleções, também é possível incluir o atributo _messages, conforme segue:

{
  hasNext: true,
  items: [
    {},
    {},
    ...
  ],
  _messages: [{
    code: "INFO",
    message: "some info message.",
    detailedMessage: "details about the info message."
  }]
}

A estrutura acima é a mínima esperada para respostas de coleção. Entretanto, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. Por exemplo:

{
  totvs_transaction_id: 1,
  total: 100,
  hasNext: true,
  items: [
    {},
    {},
    ...
  ]
}

Observe que na estrutura acima, os atributos totvs_transaction_id e total foram adicionados ao objeto de resposta, enquanto os atributos hasNext e items foram mantidos.

Mensagens de sucesso DELETE

Por padrão, nas mensagens de DELETE, a resposta deve ser enviada com HTTP Code 204 (No content) e sem corpo no retorno. 

Caso a regra de negócio necessitar de um retorno com conteúdo, este deve vir com HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.

Âncora
4xxversus5xx 4xxversus5xx

Código 4xx versus 5xx

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negócio 

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negócio ou requisição

São aqueles causados por dados inválidos nas requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP da família 4xx. Ex:

...

O padrão HATEOAS deve ser utilizado no retorno de entidades relacionadas a principal e que não são parte do recurso princiapalprincipal. Ex.

GET https://totvs.com/api/fluig/fdn/v1/users/10
{
        "id" : 10,
        "name" : "Usuário",
        "age" : 25,
		 "links": [
        { "rel": "communities",  "href": "/fdn/v1/communities/5" },
        { "rel": "permissions",  "href": "/fdn/v1/permissions/30" }
          ]             
}

...

Alterações que devem gerar uma nova versão "major":

• URIs foram removidas ou renomeadas;
• Foram removidos campos do retorno de um endpoint;
• Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
• Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
• Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "major":

• Um novo formato de retorno é suportado pelo endpoint;
• Novas propriedades são retornadas na entidade de retorno do endpoint;
• Novos parâmetros opcionais podem ser passados para o endpoint.

Documentação

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.

...

• URIs foram removidas ou renomeadas;
• Foram removidos campos do retorno de um endpoint;
• Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
• Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
• Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "major":

• Um novo formato de retorno é suportado pelo endpoint;
• Novas propriedades são retornadas na entidade de retorno do endpoint;
• Novos parâmetros opcionais podem ser passados para o endpoint.

Documentação

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.