Índice

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.

Cliente: Qualquer aplicativo que faça uma requisição para um endpoint.

Mensagem: Conteúdo enviado no corpo de uma requisição ou resposta do servidor.

Endpoint: Representa um método ou entidade que pode ser acessado através de uma requisição ao servidor.

Verbo: Tipo de requisição usada para acessar um endpoint (GET, POST, PUT, HEAD, etc).

API: Grupo de endpoints.

APIs Privadas são todas as APIs acessíveis apenas pelos times.

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:

• Determinar o tipo de recurso que está sendo exposto pelo endpoint;
• Determinar o relacionamento do recurso que está sendo criado e os recursos já existentes;
• Decidir o caminho e o nome do recurso com base no seu tipo e o seu relacionamento com os outros recursos;
• Anexar os métodos mínimos para o correto funcionamento do endpoint.

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 (além da versão da API), 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

• Entidade apresentada no plural e uso correto do parâmetro na url.
  • https://totvs.com/api/fluig/fdn/v1/users/{id}

• Ações sobre entidades no caminho da url e como parâmetro da url.
  • https://totvs.com/api/fluig/bpm/v1/workflows/{id}?action=execute
  • https://totvs.com/api/fluig/bpm/v1/workflows/{id}/send

• Relacionando entidades diretamente no caminho
  
  • https://totvs.com/api/fluig/fdn/v1/users/{alias}/communities
  • https://totvs.com/api/fluig/social/v1/communities/{id}/users

• URL com suporte a campos expansíveis
  
  • https://totvs.com/api/fluig/fdn/v1/users/{alias}?expand=prop1.subprop,prop2

• 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

• Redundância na definição da url
  • https://totvs.com/api/communty/listCommunities

• Ordenação especificada na url
  • https://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://totvs.com/api/correlationquestion/create
  • https://totvs.com/api/user/create
  • https://totvs.com/api/user/delete

...

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.

Agrupamento

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

Formatos de Data

Todos as transações de informação que suportam campos do tipo data/hora, tanto no corpo das mensagens quanto na URI, devem usar o formato de data UTC estendido (E8601DZw.d): yyyy-mm-ddThh:mm:ss.nnnnnn+|-hh:mm.

Coleções

Ordenação

Todos os endpoints de coleção devem suportar ordenação. A definição de como a lista deve ser ordenada é definida no parâmetro de url order respeitando as seguintes regras:

• O parâmetro da url deve ter o nome order;
• O valor do parâmetro order é uma lista de campos, separada por virgula (,) opcionalmente precedida pelo sinal de subtração (-);
  
• A lista deve respeitar a ordem dos campos como descrito na url para fazer a ordenação;
• Campos precedidos por um sinal de subtração (-) devem ser ordenados de forma decrescente;
• Campos que omitirem o sinal (subtração) devem ser ordenados de forma crescente.

Por exemplo, a seguinte requisição deve retornar a lista de usuários ordenados pelo nome de forma crescente e então pela idade de forma decrescente e então pelo sobrenome de forma crescente:

GET https://totvs.com.br/api/fluig/fdn/v1/users?order=name,-age,surname

Filtros

As coleções podem suportar filtro e deve usar as técnicas abaixo de acordo com a complexidade exigida pela função:

Filtros simples

Filtros simples devem usar parâmetros de query no formato propriedade=filtro e as propriedades suportadas e como elas serão interpretadas devem estar listadas na documentação do endpoint. Ex:

GET https://totvs.com.br/api/fluig/fdn/v1/users?name=john&surname=doe

Filtros complexos

Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4.

Paginação

Todos os endpoints de coleção devem suportar paginação. A definição de como a coleção deve ser paginada é definida pelos parâmetros de url page e pageSize respeitando as seguintes regras:

• Os parâmetros da url devem ter os nomes page e pageSize;

• O valor do parâmetro page deve ser um valor numérico (maior que zero) representando a página solicitada;

• O parâmetro page é opcional e na sua ausência deve ser considerado o valor 1;

• O valor do parâmetro pageSize deve ser um valor numérico (maior que zero) representando o total de registros retornados na consulta;

• O parâmetro pageSize é opcional e na sua ausência deve ser usado o valor padrão definido pela linha de negócio do endpoint (20 por exemplo). Não devem ser retornados todos os registros da consulta;

• Os parâmetros de paginação devem obedecer a semântica de multiplicador, ou seja, se o cliente solicitou page=2 com um pageSize=20 deve-se retornar os registros de 21 até 40;

...

 Por exemplo, a seguinte requisição deve retornar a quarta página de registros (dos registros 31 à 40 inclusive) de usuários:

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.

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

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

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

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

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

Abaixo descrevemos algumas situações e o método adequado a ser usado.

GET

• Quero retornar uma lista de usuários;
• Quero retornar o usuário com o id x;
• Quero retornar todas as permissões do usuário x;
• Quero retornar todos os usuário maiores de idade;

PUT

• Quero sobrescrever o usuário atual na base de dados usando os dados informados na requisição;
• Quero alterar o estado do usuário para ativo independente de outras regras;

PATCH

• Quero alterar o estado do usuário para inativo validando uma série de regras no servidor;
• Quero alterar uma propriedade do usuário e para faze-lo o servidor irá alterar também propriedades de outras entidades;
• Quero alterar a data de vencimento de uma conta mas apenas se for nos primeiros 15 dias do mês;

POST

...

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

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.

Nos casos extremos onde não houver outra maneira de representar a informação, pode-se optar por criar um cabeçalho que deve estar descrito na documentação do endpoint e este deve seguir o padrão X-[nome do produto]-[Nome do cabeçalho]

Formato das mensagens de resposta

JSON deve ser o formato padrão para mensagens e as propriedades destas mensagens devem ser escritas usando camelCase.

Todos os endpoints devem suportar este tipo de conteúdo.

Tipos de dados JSON

Os tipos de dados e a notação para os campos da mensagem JSON deve seguir os padrões descritos no documento ECMA-404.

Mensagens de erro

Para todas as mensagens que representam um erro (códigos HTTP 4xx e 5xx) deve-se retornar obrigatoriamente os campos a seguir:

{
    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 message deve descrever o erro de forma não técnica e pode ser usado pelos clientes para exibição ao usuário. O texto deste campo deve respeitar o idioma usado na requisição (definido pelo cabeçalho Accept-Language ou o padrão caso este não seja especificado). Além disso leve em consideração:
  • Não assuma que o usuário é um especialista no uso da sua API. Usuários podem incluir desenvolvedores, profissionais de TI, administradores e usuários finais;
  • Não assuma que o usuário saiba qualquer coisa sobre a implementação da função sendo exposta pelo endpoint;
  • Quando possível a mensagem deve ser construida de forma que um usuário técnico possa responder ao erro e corrigi-lo;
  • Mantenha a mensagem sucinta e, se necessário, inclua um link para a documentação de como corrigi-la.

...

Opcionalmente pode-se retornar os campos:

• helpUrl: link para a documentação do erro;
• details: Uma lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo:

{
    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",
    helpUrl: "link para a documentação do error",
    details [
        {
            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"
        },
        {
            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"
        },
        {
            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"
        }
    ]
}

Mensagens de sucesso

Mensagens de sucesso (código http 2xx devem) devem retornar diretamente a entidade que representa o objeto resultado da operação do endpoint. Ex:

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

{
  name: "John",
  sobrenome: "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: [
    {},
    {},
    ...
  ]
}

Está é a estrutura mínima esperada para respostas de coleção, porém, pode-se retornar mais campos se for necessário desde que está estrutura básica se mantenha. Ex:

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

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 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 cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized;

O cliente chamou um endpoint mas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbidden;

O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found;

O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de erro 400 - Bad Request;

O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.

Erros não esperados

...

O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;

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.

Filtro de campos da resposta

A APIs devem permitir que o cliente filtre os campos retornados nas entidades. Para isso ele deve passar o parâmetro de query com nome fields, que consiste de uma lista com o nome das propriedades JSON que serão retornadas. Os campos omitizados serão removidos do retorno (mesmo que o cliente tenha solicitado expandi-los).

Omitir o campo fields fara com que todos os campos sejam retornados.

Por exemplo, o cliente faz uma requisição para retornar os dados do cliente com id 10:

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:

GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age

{
  name: "John",
  age: 18
}

Parâmetros expansíveis

Todos os endpoints devem respeitar e suportar os campos expansíveis. E devem retornar os campos retraídos a menos que especificado na requisição através do parâmetro de url expand.

As entidades de retorno devem obedecer as regras:

Todas as propriedades que representam listas devem vir retraídas por padrão e devem usar a notação de lista vazia (Ex.: [] ).

Todas as propriedades que representam objetos devem vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )

Ao retornar uma entidade, todas as suas propriedades que representam um objeto ou coleção devem vir retraídas e a entidade deve conter um campo adicional com o nome _expandables. Esse campo é uma lista com o nome de cada uma das propriedades que podem ser passadas na url para que o endpoint inclua na responta.

Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas devem estar retraídas:

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


{
        _expandables: ["permissions", "communities", "detailedInformation"]
        id: 10
        name: "Usuário"
        age: 25
        permissions: []
        communities: []
        detailedInformation: { }
}

Caso o cliente queira expandir as propriedades, ele deve então fazer uma requisição informando o parâmetro expand na url e passando como valor uma lista separada por virgula (,) dos campos exatamente como descritos no campo _expandables.

Por exemplo, no cenário em que o cliente gostaria de expandir as comunidades da entidade usuário:

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

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

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: { }
}

Versionamento

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

Documentação

...