Histórico da Página
...
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) |
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 usado o valor padrão definido pela linha de negócio do endpoint (20 por exemplo). Não devem ser retornados todos os registros da consulta;
- 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;
...
Filtros de data Modificação (opcional)
Opcionalmente, a api pode disponibilizar o filtro especial "datemodified" para retornar registros alterados a partir de uma determinada data. Ex:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?datemodified='2018-01-01' |
ou combinar com o padrão oData para retornar apenas registros alterados em determinada data:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?$filter=datemodified ge '2018-01-01' and datemodified le '2018-01-31' |
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 usado o valor padrão definido pela linha de negócio do endpoint (20 por exemplo). Não devem ser retornados todos os registros da consulta;
- 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 e esse campo deve ter o nome hasNext.
Por exemplo, a seguinte requisição deve retornar a quarta página de registros (dos registros 31 à 40 inclusive) de usuários:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/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 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 |
Por exemplo, a seguinte requisição deve retornar a quarta página de registros (dos registros 31 à 40 inclusive) de usuários:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/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 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 |
...
Informações | ||
---|---|---|
| ||
A API deve suportar a expansão de até dois níveis de propriedade de retorno, ex: prop1.prop2.prop3. Nos casos em que o objeto tenha uma sub coleção é recomendável que o número máximo de registros dessa coleção não ultrapasse 20 registros. Se houver a necessidade de retornar mais itens, considerar criar um endpoint especifico para retornar a coleção com suporte a filtro, ordenação, etc. |
Requisições Assíncronas.
Ao realizar um POST, PUT ou DELETE em um recurso que executa seu processamento de maneira assíncrona, o mesmo DEVE retornar o código 202 Accepted, com cabeçalho location apontando para um recurso temporário que permita o acompanhamento do status da requisição.
Informações | ||
---|---|---|
| ||
A implementação do modelo assíncrono não é obrigatório. A opção por este modelo deve basear no tempo e recurso necessário para o processamento de uma requisição. |
Processando
Ao realizar o GET no recurso temporário, enquanto ainda estiver sendo processado, o mesmo DEVE retornar o código 200 e um JSON com a propriedade status definida como “pending”. Esse retorno PODE, e é uma boa prática, retornar a propriedade progress, informando o percentual de conclusão da operação solicitada.
Outra propriedade que PODE constar nesse retorno é a canCancel. Quandodefinida como “true”, significa que cancelar aquele processamento é permitido para o client. Quando inexistente, ou definida como “false”, o cancelamento não está permitido.
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "status": "pending", "progress": "30%", "canCancel": true } |
Para cancelar a execução do processamento, quando permitido, o client deve executar DELETE no recurso temporário.
Finalizada – Erro
Ao acessar o recurso temporário que finalizou seu processamento com erros, retorna o erro adequado, conforme definido em Mensagens de Erro e Código 4xx versus 5xx
Finalizada – Sucesso
Ao acessar o recurso temporário que finalizou seu processamento com sucesso, o mesmo DEVE retornar o código 303 (See Other) com o cabeçalho Location, apontando para endereço do real recurso criado.
A deleção do recurso temporário não é obrigatória e PODE ser feita através de DELETE do client, ou através do próprio server, após um tempo determinado para expirá-lo. Nesse segundo caso, ao tentar acessá-lo DEVE retornar 410 (Gone).
Versionamento
Padrão HATEOAS.
Esse estilo de arquitetura permite usar links no conteúdo da resposta para que o cliente possa navegar dinamicamente para o recurso apropriado. Isso é conceitualmente o mesmo que um usuário da Web navegando pelas páginas e clicando nos hiperlinks apropriados para atingir uma meta final.
O padrão HATEOAS deve ser utilizado no retorno de entidades relacionadas a principal e que não são parte do recurso princiapal. Ex.
Bloco de código | ||
---|---|---|
| ||
GET https | ||
Bloco de código | ||
| ||
http://totvs.com/api/fluig/fdn/v1/users http://totvs.com/api/fluig/fdn/v1.5/users http://totvs.com/api/fluig/fdn/v2/users |
Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.
Informações | ||
---|---|---|
| ||
A politica de depreciação deve definir o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e estará disponível. A politica pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final. |
Quando alterar a versão?
O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.
Alterações que devem gerar uma nova versão "major":
- URIs foram removidas ou renomeadas;
- Foram removidos campos do retorno de um endpoint;
- Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
- Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
- Um novo endpoint foi adicionado a API.
Alterações que NÃO devem gerar uma nova versão "major":
- Um novo formato de retorno é suportado pelo endpoint;
- Novas propriedades são retornadas na entidade de retorno do endpoint;
- Novos parâmetros opcionais podem ser passados para o endpoint.
Aviso | ||
---|---|---|
| ||
Em relação a APIs baseadas em mensagem padronizada TOTVS o esquema de versionamento muda em alguns pontos. Por isso, quando for o caso, recomenda-se utilizar os critérios indicados neste link. |
Documentação
Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação. Além disso deve ser gerado um documento OpenAPI com as definições da API./10
{
"id" : 10,
"name" : "Usuário",
"age" : 25,
"links": [
{ "rel": "communities", "href": "/fdn/v1/communities/5" },
{ "rel": "permissions", "href": "/fdn/v1/permissions/30" }
]
}
|
Versionamento
Bloco de código | ||
---|---|---|
| ||
http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/v2/users |
Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.
Informações | ||
---|---|---|
| ||
A politica de depreciação deve definir o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e estará disponível. A politica pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final. |
Quando alterar a versão?
O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.
Alterações que devem gerar uma nova versão "major":
- URIs foram removidas ou renomeadas;
- Foram removidos campos do retorno de um endpoint;
- Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
- Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
- Um novo endpoint foi adicionado a API.
Alterações que NÃO devem gerar uma nova versão "major":
- Um novo formato de retorno é suportado pelo endpoint;
- Novas propriedades são retornadas na entidade de retorno do endpoint;
- Novos parâmetros opcionais podem ser passados para o endpoint.
Aviso | ||
---|---|---|
| ||
Em relação a APIs baseadas em mensagem padronizada TOTVS o esquema de versionamento muda em alguns pontos. Por isso, quando for o caso, recomenda-se utilizar os critérios indicados neste link. |
Documentação
Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação. Além disso deve ser gerado um documento OpenAPI com as definições da API.
{
"id":10,
"name":"Usuário",
"age":25,
"links":[
{
"rel":"communities",
"href":"/fdn/v1/communities/5"
},
{
"rel":"permissions",
"href":"/fdn/v1/permissions/30"
}
]
}