...

Introdução

Este documento define os padrões que devem ser adotados durante a implementação de novas APIs publicas ou privadas na plataforma TOTVS incluindo:

...

Termos e Nomenclaturas

...

Os termos deve, não deve, requerido, pode, não pode, recomendado, opcional devem ser interpretados como descritos no padrão RFC-2119.

...

APIs Publicas são todas as APIs que podem ser acessadas por clientes externos aos times de desenvolvimento.

Comitê

Criamos um comitê interno, formado com um integrante de cada squad, para discutir e garantir a execução dos padrões definidos neste documento.

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:

...

• Ordenando e paginando coleções
  • https://totvs.com/api/fluig/fdn/v1/users?order=name,-age&page=2&pageSize=20

Exemplo de URLS NÃO amigáveis e que deve ser evitadas

...

• Identificador da entidade definido como parâmetro e não como caminho (na url)
  • https://totvs.com/api/document/permissions?documentId={id}
    

...

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

...

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 {dominio}/api/{produto}/{modulo}/{versão}/. Ex: https://fluig.totvs.com/api/fluig/ecm/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. 

Ex:

GET http://totvs.com/api/fluig/ecm/v1/documents
GET http://totvs.com/api/fluig/bpm/v1/workflows
GET http://totvs.com/api/fluig/lms/v1/classes

...

GET https://totvs.com.br/api/fluig/fdn/v1/users?page=4&pageSize=10

Métodos suportados

...

Endpoints devem usar os métodos HTTP adequados e devem respeitar a idempotência da operação.

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.

Método	Descrição	Idempotente
GET	Retorna o valor corrente do objeto.	Sim
PUT	Sobrescreve o objeto quando aplicável. Por exemplo: O cliente gostaria de sobrescrever o usuário com novos valores: Bloco de código language text PUT http://totvs.com/api/users/10 { name: "", age: 20, ... } Informações title Importante Caso o cliente não informe alguma propriedade para ser atualizada, está deve ser considerada nula. Está informação deve estar clara na documentação do método para que o cliente não há utilize inadvertidamente, ou pode-se optar por não implementá-la.	Sim
DELETE	Exclui o objeto.	Sim
POST	Cria um novo objeto ou submete um comando ao objeto.	Não
HEAD	Retorna os metadados da requisição em casos em que o cliente não precisa do corpo das requisições do tipo GET.	Sim
PATCH	Também usado para atualizar uma entidade, mas diferente do PUT, recebe em seu corpo uma série de instruções ou o estado no qual o cliente gostaria que a entidade estivesse no final da operação. Deve ser tratado de forma atômica, ou seja, ou todas as instruções foram completadas com sucesso ou deve retornar erro ao cliente. PATH pode causar efeitos colaterais e portanto não é considerado seguro ou idempotente. Bloco de código language text PATCH http://totvs.com/api/fluig/fdn/v1/users/10 { name: "Novo nome do usuário" } O servidor deverá implementar o serviço de modo que apenas o nome do usuário seja atualizado e todas as outras propriedades sejam mantidas.	Não
OPTIONS	Deve retornar pelo menos o campo Allow no cabeçalho da resposta listando os verbos suportados pelo endpoint.	Sim

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

202 Accepted
Location: https://totvs.com/api/fluig/fdn/v1/users/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.

...

{
    code: "Código identificador do erro",
    message: "Literal no idioma da requisição descrevendo o erro para o cliente",
    detailedMessage: "Mensagem técnica e mais detalhada do erro"
}

• O campo code deve identificar unicamente o erro na documentação da API;
  
  

...

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

{
  _expandables: ["permissions"],
  name: "John",
  sobrenome: "Doe",
  age: 18,
  country: US,
  permissions: {}
}

Caso os únicos campos interessantes para o cliente sejam o "name" e "age" ele pode reduzir a quantidade de dados usando o parâmetro fields. Ex:

...

Note que as propriedades do objeto expandido devem vir retraídas por padrão. O cliente pode solicitar que as propriedades dos objetos sejam expandidas separando as sub-propriedades com ponto (.). Usando o exemplo acima, o usuário gostaria de expandir as permissões das comunidades da entidade usuário: 

GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities.permissions

{
        _expandables: ["permissions", "detailedInformation"]
        id: 10
        name: "Usuário"
        age: 25
        permissions: []
        communities: [{
            name: "Vendas",
            photoUrl: "https://totvs.com/communities/1/photo",
            permissions: {
                isAdmin: true,
                canView: true
            }
        }, {
            name: "Outra comunidade",
            photoUrl: "https://totvs.com/communities/2/photo",
            permissions: {
                isAdmin: true,
                canView: true
            }
        }]
        detailedInformation: { }
}

...

http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/v2/users

...