Í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 do fluig 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 do fluig.

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.

...

Estrutura de URLs

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

...

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. Apesar de não definirmos uma estrutura única com uma séria de regras para esses agrupamentos (já que não conseguimos generalizar todas as linhas de negócio) 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.

...

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

Formatos de Data

Todos as transações de informação que suportam campos de data, tanto no corpo das mensagens quanto nas urls, devem usar o formato definido no documento ISO-8601 no formato EXTENDIDO.

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:

...

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://fluig.totvs.com.br/api/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.

Filtros como ações

Além das opções acima é possível definir um filtro como uma ação e usar o método POST. Neste caso a url deve seguir as boas praticas para não poluir as URIs da API.

...

GET https://fluig.totvs.com.br/api/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.

...

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

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-fluig-[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:

...

Mensagens de sucesso

Mensagens de sucesso devem ser retornadas para todos os códigos http 2xx e devem ter pelo menos o campo data que representa o objeto resultado da operação do endpoint. Ex:

{
  data: {}
}

Â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 itens que representam a lista de itens retornados.

{
  data: {
    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.

...

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.

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.

...

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

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

    }
}

...

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