...

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

Definir práticas e padrões consistentes para todos os endpoints das APIs do fluigda 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 plataforma fluig TOTVS acessíveis através de APIs facilmente compreendidas e documentadas para desenvolvedores e consumidores.

...

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

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

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

...

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

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.

...

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

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

Relacionando entidades diretamente no caminho
- https://fluig.totvs.com/api/users/{alias}/communities
- https://fluig.totvs.com/api/communities/{id}/users

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

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

...

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

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

Identificador da entidade definido como parâmetro e não como caminho (na url)
- https://fluig.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 do fluig deve ser identificado com uma url maior que 2000 caracteres para garantir que todos os navegadores modernos sejam suportados.

...

Bloco de código

language	xml

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

...

Bloco de código

language	text

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

...

Bloco de código

language	text

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

...

Bloco de código

language	text

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

...

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

POST http://fluig.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

PATH foi padronizado pelo IETF como o método utlizado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas. Por exemplo: O cliente gostaria de atualizar o nome do usuário e para isso vai usar o endpoint de atualização de usuários

Bloco de código

language	text

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

...

Verbo

Usado para

Tipo de operação

Código de sucesso

Detalhes

POST

Criar uma entidade

Síncrona

201

Além do código de sucesso deve retornar a nova entidade criada.

PATCH ou PUT

Atualizar uma entidade

Síncrona

200

Além do código de sucesso deve retornar a nova entidade atualizada.

POST, PATCH, PUT

Criar ou atualizar entidade

Assíncrona

202

O código 202 informa ao cliente que o serviço aceitou a requisição para processamento e que isso pode levar um tempo para concluir. Nesse caso o endpoint deve retornar o campo Location no cabeçalho da resposta apontando para onde a nova entidade poderá ser encontrada. Por exemplo, considere o endpoint de cadastro assíncrono de usuários:

Bloco de código

language	text

POST https://fluig.totvs.com/api/users
{
 ...
}

DEVE retornar como responta:

Bloco de código

language	text

202 Accepted
Location: https://fluig.totvs.com/api/users/10

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

...

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 produto]-[Nome do cabeçalho]

Formato das mensagens de resposta

...

O campo detailedMessage deve descrever o erro de forma mais técnica e pode conter referências que ajudem na correção / localização do erro no contexto do servidor do fluig.

Opcionalmente pode-se retornar os campos:

...

Bloco de código

language	js

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


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

...

Bloco de código

language	js

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

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

...

Bloco de código

language	js

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

    }
}

...

Bloco de código

language	js

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

Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.

Informações

title	Politica de depreciação.

A politica de depreciação deve definir o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e estará disponível. A politica é pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final.

Quando alterar a versão?

O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.

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

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 "minor":

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 do fluig. Além disso deve ser gerado um documento SWAGGER com as definições da API.

Páginas filhas

Versões comparadas

Versão antiga 55

Nova versão 56

Chave

Comitê

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

Formato das mensagens de resposta

Quando alterar a versão?

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

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

Documentação

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 55

Nova versão 56

Chave

Comitê

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

Formato das mensagens de resposta

Quando alterar a versão?

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

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

Documentação