...

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 DEVE obrigatoriamente ser incluído no pull request de novas APIs publicas e cadas um deles é responsável por garantir a correta disseminação e implementação dentro de seu próprio time das APIs privadas.

...

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

APIs Publicas são todas as APIs que podem ser acessadas por clientes externos aos times de desenvolvimento do fluig.

...

• 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 amigáveis 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}
    
    

...

PRECISAMOS FAZER UMA POC TESTANDO VARIOS JARS E UM WAR PADRE

• /me
• /por card?
  

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:

...

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

Filtros

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 nem todos os endpoints precisam ter filtro. 

As coleções que suportarem filtro DEVEM suportar parâmetros no formato propriedade=filtro e as propriedades suportadas DEVEM estar listadas na documentação do endpoint.

 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:

...

Na tabela abaixo serão listados os métodos que DEVEMser suportados. Nem todos os endpoints devem suportar todos os métodos, mas os utilizados que o fizerem DEVEM respeitar a utilização conforme descrita.

...

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.

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

...

Erros de negócio ou requisição são aqueles causados por dados inválidos na requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem DEVEM obrigatoriamente retornar um código HTTP da família 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 só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not AcceptableO cliente chamou um endpoint para subir um documento mas o usuário autenticado passou o limite de espaço estipulado para seu perfil. Deve retornar o código 507 - Insufficiente Storage;

Erros não esperados são os erros não tratados ou não intencionais. Esse tipo de erro devesempre retornar códigos HTTP da família 5xx. Ex:

1. O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
2. 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

...