Histórico da Página
...
- 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.
Nota | ||
---|---|---|
| ||
Atente-se para esta documentação. Para garantir um bom desenvolvimento de APIs publicas ou privadas, é imprescindível que os passos a seguir sejam respeitados. |
Termos e Nomenclaturas
Os termos DEVE, NÃO DEVE, REQUERIDO, PODE, NÃO PODE, RECOMENDADO, OPCIONAL devem ser interpretados como descritos no padrão RFC-2119.
...
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.
...
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 devem ser considerados ao criar uma URL:
- Ao referenciar uma entidade na URL ela DEVE 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 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.
...
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 url 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 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:
...
As coleções que suportarem filtro DEVEM devem suportar parâmetros no formato propriedade=filtro e as propriedades suportadas DEVEM devem estar listadas na documentação do endpoint. Ex:
...
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 deve ser um valor numérico maior que zero representando a página solicitada;
- O parâmetro page é OPCIONAL opicional e na sua ausência deve ser considerado o valor 1;
- O valor do parâmetro pageSize DEVE deve ser um valor numérico maior que zero representando o total de registros retornados na consulta;
- O parâmetro pageSize é OPCIONAL 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 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 deve ter o nome hasNext hasNext.
Por exemplo, a seguinte requisição deve retornar a terceira página de registros (dos registros 31 à 40 INCLUSIVEinclusive) de usuários:
Bloco de código | ||
---|---|---|
| ||
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.
Na tabela abaixo serão listados os métodos que DEVEMdevemser suportados. Nem todos os endpoints devem suportar todos os métodos, mas os que o fizerem DEVEM devem respeitar a utilização conforme descrita.
Método | Descrição | Idempotente | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | Retorna o valor corrente do objeto. | Sim | ||||||||||
PUT | Sobrescreve o objeto quando aplicável. Por exemplo: O cliente gostaria de sobrescrever o usuário com novos valores:
| Sim | ||||||||||
DELETE | Exclui o objeto. | Sim | ||||||||||
POST | Cria um novo objeto ou submete um comando ao objeto. | Não | ||||||||||
HEAD | Retorna os metadados da requisição em casos em que o cliente não precisa do corpo das requisições do tipo GET. | Sim | ||||||||||
PATCH | PATH foi padronizado pelo IETF como o método utlizado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas. Por exemplo: O cliente gostaria de atualizar o nome do usuário e para isso vai usar o endpoint de atualização de usuários
O servidor deverá implementar o serviço de modo que apenas o nome do usuário seja atualizado e todas as outras propriedades sejam mantidas. | Não | ||||||||||
OPTIONS | Deve retornar pelo menos o campo Allow no cabeçalho da resposta listando os verbos suportados pelo endpoint. | Sim |
...
Verbo | Usado para | Tipo de operação | Código de sucesso | Detalhes | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
POST | Criar uma entidade | Síncrona | 201 | Além do código de sucesso deve retornar a nova entidade criada. | ||||||||||
PATCH ou PUT | Atualizar uma entidade | Síncrona | 200 | Além do código de sucesso deve retornar a nova entidade atualizada. | ||||||||||
POST, PATCH, PUT | Criar ou atualizar entidade | Assíncrona | 202 | O código 202 informa ao cliente que o serviço aceitou a requisição para processamento e que isso pode levar um tempo para concluir. Nesse caso o endpoint DEVE deve retornar o campo Location no cabeçalho da resposta apontando para onde a nova entidade poderá ser encontrada. Por exemplo, considere o endpoint de cadastro assíncrono de usuários:
DEVE retornar como responta:
|
...
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.
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 podem retornar valores em formatos diferentes dos informados. |
Accept-Encoding | Gzip, deflate | Endpoints DEVEM devem suportar codificação GZIP e DEFLATE por padrão exceto em casos em que isso implique na performance. |
Accept-Language | "en", "es", "pt" | Especifica o idioma preferencial da resposta. Os endpoints DEVEM devem suportar e respeitar estes valores em casos em que uma mensagem é retornada ao usuário. Caso o idioma informado não seja suportado, deve-se retornar ao idioma padrão (pt). |
Content-Type | tipo de conteúdo | Tipo do conteúdo sendo passado na requisição. O endpoint DEVE deve respeitar esta informação na hora de interpretar a informação passada pelo cliente ou retornar um erro apropriado caso o valor não for suportado. |
Padrões de cabeçalhos de respostas
Endpoints DEVEM devem retornar estes cabeçalhos em todas as repostas, a menos que explicitamente citado o contrário na coluna obrigatório.
Cabeçalho | Obrigatório | Descrição |
---|---|---|
Date | Em todas as respostas | Hora em que a resposta foi processada baseada no calendário do servidor no formato estipulado em RFC 5322. Ex: Wed, 24 Aug 2016 18:41:30 GMT . |
Content-Type | Em todas as respostas | O tipo de conteúdo enviado do endpoint para o servidor. |
Content-Encoding | Em todas as respostas | GZIP ou DEFLATE como for apropriado. |
...
Cabeçalhos customizados
Cabeçalhos customizados NÃO DEVEM ser 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 DEVEM 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 deve estar descrito na documentação do endpoint e este DEVE deve seguir o padrão X-fluig-[Nome do cabeçalho]
Formato das mensagens de resposta
JSON DEVE deve ser o formato padrão para mensagens e as propriedades destas mensagens DEVEM devem ser escritas usando camelCase.
Todos os endpoints DEVEM devem suportar este tipo de conteúdo.
...
Os tipos de dados e a notação para os campos da mensagem JSON DEVE deve seguir os padrões descritos no documento ECMA-404.
Informações | ||
---|---|---|
| ||
Os campos do JSON que representam data DEVEM devem usar os formato definido no documento ISO-8601 no formato EXTENDIDO. |
...
Bloco de código | ||
---|---|---|
| ||
{ 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;
Informações Todos os códigos de error DEVEM devem estar mapeados e listados na documentação da API.
- O campo helpUrl deve apontar 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.
...
Mensagens de sucesso
Mensagens de sucesso DEVEM devem ser retornadas para todos os códigos http 2xx e DEVEM devem ter pelo menos o campo content que representa o objeto resultado da operação do endpoint. Ex:
...
Nos casos em que o resultado da operação do endpoint represente uma coleção, os itens devem estar agrupados em um objeto com as propriedades hasNext, indicando se existe uma próxima página com mais registros para aquela coleção e items itens que representa a lista de itens retornados.
...
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:
- O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized;
- 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;
- 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;
- 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;
- 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 Acceptable.
...
- O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
- 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 devem respeitar e suportar os campos expansíveis. E DEVEM devem retornar os campos retraídos a menos que especificado na requisição através do parâmetro de url expand.
As entidades de retorno DEVEM devem obedecer as regras:
- Todas as propriedades que representam listas DEVEM devem vir retraídas por padrão e DEVEM devem usar a notação de lista vazia (Ex.: [] ).
- Todas as propriedades que representam objetos DEVEM 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 ou coleção DEVEM devem vir retraídas e a entidade DEVE conter 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.
...
Caso o cliente queira expandir as propriedades, ele DEVE 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.
Informações |
---|
Apenas o primeiro nível das propriedades deve ser expandido, ou seja, se o objeto expandido tiver propriedades expansíveis elas devem vir retraídas. |
...
Note que as propriedades do objeto expandido DEVEM devem vir retraídas por padrão. O cliente PODE 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:
...
Versionamento
- API interna deve seguir esse padrão, mas é independe do versionamento. Deve estar documentado (tecnica) para as novas.
- Validar como passar a versão URL ou header. Testar com o Paulo.
Dicas de como implementar os métodos para tentar manter um padrão de implementação.
Documentação
Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica DEVEM devem estar documentadas na página de documentação do fluig. Além disso DEVE deve ser gerado um documento SWAGGER com as definições da API.