Incluir Página
framework:Guia de implementação de API V2.0 framework:Guia de implementação de API V2.0

Í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 incluido:

• 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 e documentadas para desenvolvedores e consumidores;
   

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.

Cada um dos membros 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.

Nomenclaturas

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

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.

Estrutura de URLs

Os caminhos definidos para cada endpoint devem ser de fácil leitura e significativos para o cliente para facilitar a sua descoberta e adoção. Os pontos abaixo DEVEM ser considerados ao criar uma URL:

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

Exemplo de URLs amigáveis:

Colocar exemplo de filtro e expansíveis

...

• https://fluig.totvs.com/api/users/{id}

...

• https://fluig.totvs.com/api/workflows/{id}?action=execute
• https://fluig.totvs.com/api/workflows/{id}/send

...

• https://fluig.totvs.com/api/users/{alias}/communities
• https://fluig.totvs.com/api/communities/{id}/users

...

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

Agrupamento

PRECISAMOS FAZER UMA POC TESTANDO VARIOS JARS E UM WAR PADRE

• /me
• /por card?
  

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:

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

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

Filtros

Marcelo - pesquisar schin|skin|scan|etc filter. mas tem que ser via get provavel que com q param;

 Paulo - Vai procurar um framework que faça o parse dessa string.

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:

• Os parâmetros da 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 é 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 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 (linkar) 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:

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 usarem DEVEM obedecer as regras descritas aqui.

Padrões de cabeçalhos de responta

Endpoints DEVEM retornar estes cabeçalhos em todas as reposta 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 DEVE 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 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.

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:

{
    code: "Código identificador do erro",
    helpUrl: "link para a documentação do error",
    message: "Literal no idioma da requisição descrevendo o erro para o cliente",
    detailedMessage: "Mensagem técnica e mais detalhada do erro"
}

...

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

...

Mensagens de sucesso

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

{
  content: {}
}

Mensagens de sucesso para coleções

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.

{
  hasNext: true,
  content: [
    {},
    {},
    ...
  ]
}

Código 4xx versus 5xx

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negócio ou requisição são aqueles causados por dados inválidos na requisiçõe 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 passou o limite de espaço estipulado para seu perfil. Deve retornar o código 507 - Insufficiente Storage;

...

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

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

As entidades de retorno DEVEM obedecer as regras:

• Todas as propriedades que representam listas DEVEM vir retraídas por padrão e DEVEM usar a notação de lista vazia (Ex.: [] ).
• Todas as propriedades que representam objetos DEVEM vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )
  

Ao retornar uma entidade todas as suas propriedades que representam um objeto OU coleção DEVEM vir retraídas e a entidade DEVE conter um campo adicional com o nome _expandables. Esse campo é uma lista com o nome de cada uma das propriedades que podem ser passadas na url para que o endpoint inclua na responta.

Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas devem estar retraídas:

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

{
  _expandables: ["permissions", "communities", "detailedInformation"],
  id: 10,
  name: "Usuário",
  age: 25,
  permissions: [],
  communities: [],
  detailedInformation: {},
  ...
}

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

Por exemplo, no cenário em que o cliente gostaria de expandir as comunidades da entidade usuário:

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

{
  _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: {},
  ...
}

Note que as propriedades do objeto expandido DEVEM vir retraídas por padrão. O cliente PODE solicitar que as propriedades dos objetos sejam expandidas separando as sub-propriedades com ponto (.). Usando o exemplo acima, o usuário gostaria de expandir as permissões das comunidades da entidade usuário:

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

{
  _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: {},
  ...
}

Versionamento

...

Dicas de como implementar os métodos para tentar manter um padrão de implementação.

Documentação

...