Histórico da Página
...
Cada um dos membros deve obrigatoriamente ser incluído no pull request de novas APIs publicas e cada um deles é responsável por garantir a correta disseminação e implementação dentro de seu próprio time das APIs privadas.
Segmento | Membro |
---|---|
Fluig | |
Integração | |
RM | |
Protheus | |
Datasul |
Estrutura de URLs
Como regra geral seguimos os passos abaixo sempre que precisarmos criar um novo recurso:
...
Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio, criar um novo grupo de endpoints implica em preocupações como versionamento, disponibilidade e documentação. Usamos como base a estrutura "{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}". Ex: https://fluig.totvs.com/api/fluig/ecm/v1/users. A partir deste ponto deve-se considerar como regra básica a complexidade necessária para descobrir estes endpoints, ou seja, o agrupamento deve facilitar e não complicar a descoberta dos serviços.
...
Informações |
---|
APIs escritas utilizando o protocolo de mensagem padronizada não devem definir o nome do produto na URL. A ideia de APIs padronizadas é que a mesma assinatura atenda diferentes produtos. A assinatura de API padronizada segue a nomenclatura abaixo: "{protocolo}://{host}/{api}/{agrupador}/{dominio}{versao}/{recurso}" |
Estrutura OAS (Open Api Specification 3.0.1):
Bloco de código | ||
---|---|---|
| ||
openapi: 3.0.1 info: title: Estrutura de Url para API's description: 'Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio. Usamos como base a estrutura "{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}"' version: '1.0' externalDocs: url: 'http://tdn.totvs.com/display/INT/Guia+de+implementacao+das+APIs+TOTVS' servers: - url: '{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}' variables: protocolo: default: https enum: - http - https host: default: host api: default: api produto: default: produto agrupador: default: agrupador versao: default: versao recurso: default: recurso paths: {} components: {} |
...
Exemplo de filtros no padrão odata:
Operator | Description | Example |
Logical Operators | ||
eq | Equal | /Suppliers?$filter=Address/City eq 'Redmond' |
ne | Not equal | /Suppliers?$filter=Address/City ne 'London' |
gt | Greater than | /Products?$filter=Price gt 20 |
ge | Greater than or equal | /Products?$filter=Price ge 10 |
lt | Less than | /Products?$filter=Price lt 20 |
le | Less than or equal | /Products?$filter=Price le 100 |
and | Logical and | /Products?$filter=Price le 200 and Price gt 3.5 |
or | Logical or | /Products?$filter=Price le 3.5 or Price gt 200 |
not | Logical negation | /Products?$filter=not endswith(Description,'milk') |
Grouping Operators | ||
( ) | grouping | /Products?$filter=(Price lt 5) |
Filtros de data Modificação (opcional)
...
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 o fizerem 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 | Também usado para atualizar uma entidade, mas diferente do PUT, recebe em seu corpo uma série de instruções ou o estado no qual o cliente gostaria que a entidade estivesse no final da operação. Deve ser tratado de forma atômica, ou seja, ou todas as instruções foram completadas com sucesso ou deve retornar erro ao cliente. PATH pode causar efeitos colaterais e portanto não é considerado seguro ou idempotente.
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 |
Corpo de mensagem e Query String
...
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:
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, 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 retornar o campo Location no cabeçalho da resposta apontando para um recurso temporário que permita o acompanhamento do status da requisição. Por exemplo, considere o endpoint de cadastro assíncrono de usuários:
DEVE retornar como resposta:
|
Como escolher o método adequado
...
A utilização destes cabeçalhos não é obrigatória para todos os endpoints, mas os que os 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 retornar valores em formatos diferentes dos informados. |
Accept-Encoding | Gzip, deflate | Endpoints 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 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 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 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 utilizados para representar qualquer estado, valor ou ação sobre a entidade representada pela url. Isso quer dizer que cabeçalhos 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.
...
...