...

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:

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

...

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

...

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.

...

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

...

Todos os endpoints de coleção devem suportar 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  deve ter o nome order;
• O valor do parâmetro order é uma lista de campos, separada por virgula (,) opcionalmente precedida pelos sinais de adição (+) ou 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 precedidos por um sinal de adição (+) devem ser ordenados de forma crescente;
• Campos que omitirem o sinal (de adição ou 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:

...

Todos os endpoints de coleção devem suportar 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 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 é opicional 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 considerado o valor 20;
• Os parâmetros de paginação devem obedecer 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;
• A resposta de uma requisição com paginação deve retornar um campo indicando se existe uma próxima página disponível conforme descrito na mensagem de sucesso de lista e esse campo deve ter o nome hasNext.

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

...

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.

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

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

...

A utilização destes cabeçalhos não é obrigatória para todos os endpoints, mas os que os utilizarem devem 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 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.

...

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

...