...

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

• 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 mais fáceis facilmente compreendidas e documentadas para desenvolvedores e consumidores.

...

• Ao referenciar uma entidade na URL ela DEVE estar no plural. Ex. /users 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 URL ou na urlURL.

Exemplo de URLs amigáveis:

• 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

Exemplo de URLS NÃO amigaveis e que deve ser evitadas:

• 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 maximo máximo para a url nenhum endpoint do fluig deve ser identificado com uma url maior que 2000 caracteres para garantir que todos os navegares modernos sejam suportados.

...

• 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 pelos sinal 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.

...

Os campos como query param e os campos tem que estar documentados no swagger informando o tipo de filtro que é aplicado. Cada endpoint pode suportar os campos que quiser. e E nem todos os endpoints precisam ter filtro. 

...

Na tabela abaixo serão listados os métodos que DEVEMser suportados. Nem todos os endpoints devem suportar todos os métodos, mas os que usarem utilizados 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 usarem utilizarem DEVEM obedecer as regras descritas aqui.

Padrões de cabeçalhos de

...

respostas

Endpoints DEVEM retornar estes cabeçalhos em todas as reposta repostas, a menos que explicitamente citado o contrário na coluna obrigatório

...

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 DEVEDEVEM 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éria série de cabeçalhos para quase todas as situações e estas sempre tem precedência a um cabeçalho customizado.

...

Formato das mensagens de resposta

O JSON DEVE ser o formato padrão para mensagens e as propriedades destas mensagens DEVEM ser escritas usando camelCase.

...

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

  Informações
  Todos os códigos de error DEVEM estar mapeados e listados na documentação da API.

• O campo helpUrl deve apontar para diretamente para documentação do erro na API;
• 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);
• 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.
  
  

...

Nos casos em que o resultado da operação do endpoint represente uma coleção além do campo content deve ser retornado o campo hasNext, indicando se existe uma próxima página com mais registros para aquela coleção.

...

Erros de negócio ou requisição são aqueles causados por dados inválidos na requisiçõe requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP 4xx. Ex:

1. O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized
2. 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
3. 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
4. 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 error 400 - Bad Request
5. O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable
6. O cliente chamou um endpoint para subir um documento mas o usuário logado autenticado passou o limite de espaço estipulado para seu perfil. Deve retornar o código 507 - Insufficiente Storage;

...

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 atráves através do parâmetro de url expand.

...

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 (, (virgula) dos  dos campos exatamente como descritos no campo _expandables.

...