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:
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.
Squad | Membro |
---|---|
SDK | Marcelo De Aguiar |
Identity / Portal | Paulo Roberto Francisco Junior |
LMS | Diego Lopes |
BPM | Gustavo Martins De Souza |
PAAS / Fundação | Vanei Anderson Heidemann |
ECM | Andre Felipe Joriatti |
Integração | Danilo Pacheco Martins |
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.
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.
Exemplo de URLs amigáveis:
https://fluig.totvs.com/api/users/{id}
https://fluig.totvs.com/api/workflow/{id}?action=execute
https://fluig.totvs.com/api/users/{alias}/communities
Exemplo de URLS NÃO amigaveis e que deve ser evitadas:
https://fluig.totvs.com/api/communty/listCommunities
https://fluig.totvs.com/api/communty/listCommunitiesWithRelevance
https://fluig.totvs.com/api/correlationquestion/create
https://fluig.totvs.com/api/user/create
https://fluig.totvs.com/api/user/delete
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
Mais informações sobre a escolha do valor máximo de caracteres pode ser consultada em: https://blogs.msdn.microsoft.com/ieinternals/2014/08/13/url-length-limits/ |
Endpoints devem usar os métodos HTTP adequados e devem respeitar a idempotência da operação.
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 usarem DEVEM respeitar a utilização conforme descrita.
Método | Descrição | Idempotente |
---|---|---|
GET | Retorna o valor corrente do objeto. | Sim |
PUT | Sobrescreve o objeto ou cria um novo objeto quando aplicável. | Sim |
DELETE | Exclui o objeto. | Sim |
POST | Cria um novo objeto ou submete um comando ao objeto. | Não |
HEAD | Retorna os metadados de um objeto em requisições do tipo GET. Endpoints que suportam o método GET PODEM suportar o método HEADER. | Sim |
PATCH | Aplica uma atualização parcial no objeto. | Não |
OPTIONS | Retorna informações sobre uma requisição; ver abaixo para mais detalhes. | Sim |
Operações do tipo POST DEVEM retornar a localização de qualquer objeto criado que tenha um identificador.
Por exemplo: Um serviço responsável por criar um usuário descrito como:
POST http://fluig.totvs.com/api/users |
Deveria responder com algo similar a:
201 Created Location: https://fluig.totvs.com/api/users/10 |
Onde 10 é o id do novo usuário criado.
Apesar de ambos atualizarem um objeto é importante notar que existe uma diferença na implementação destes métodos.
PUT DEVE ser considerado uma substituição total do objeto, ou seja, caso o cliente deixe de enviar uma propriedade para ser atualizada ela será considerada nula e poderá inadvertidamente remover valores do objeto.
PATH foi padronizado pelo IETF como o método usado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas.
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.
Header | Tipo | Descrição |
---|---|---|
Authorization | literal | Cabeçalho usado para autorização das requisições |
Date | data | Data e hora da requisição com base no calendário do cliente no formato estipulado em RFC 5322 |
Accept | enumerador de tipo de conteúdo | O tipo de conteúdo esperado para a resposta como por exemplo:
De acordo com os padrões HTTP, este valor é apenas uma dica para o servidor e as respostas PODEM retornar valores em formatos diferentes dos informados. |
Accept-Encoding | Gzip, deflate | Endpoints DEVEM suportar codificação GZIP e DEFLATE quando aplicável. |
Accept-Language | "en", "es", "pt" | Especifica o idio preferencial da resposta. Endpoints DEVEM suportar e respeitar estes valores em casos em que uma mensagem é retornada ao usuário. |
Content-Type | tipo de conteúdo | Tipo do conteúdo informado na requisição. |
Durante a construção das mensagens que serão transmitidas entre o cliente e endpoint deve-se garantir a consistência entre nomes de propriedades e objetos quando os mesmo fizerem parte de um mesmo grupo ou assunto.
Mensagens de retorno do endpoint para o cliente devem obedecer a estrutura definida para mensagens de erro ou mensagens de sucesso
Todos as respostas de erro (códigos HTTP 4xx e 5xx) devem retornar uma mensagem contendo 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" } |
Em alguns casos se faz necessário retornar mais campos do que os estipulados acima. Nestes casos a informação deve ser considerada opcional do ponto de vista do cliente, ou seja, o cliente não deve depender dela para o tratamento do erro. |
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:
Erros não esperados são os erros não tratados ou não intencionais. Esse tipo de erro deve sempre retornar códigos HTTP 5xx. Ex: