Histórico da Página
...
- Entidade apresentada no plural e uso correto do parâmetro na url.
- https://totvs.com/api/fluig/fdn/v1/users/{id}
- Ações sobre entidades no caminho da url e como parâmetro da url.
- https://totvs.com/api/fluig/bpm/v1/workflows/{id}?action=execute
- https://totvs.com/api/fluig/bpm/v1/workflows/{id}/send
- Relacionando entidades diretamente no caminho
- https://totvs.com/api/fluig/fdn/v1/users/{alias}/communities
- https://totvs.com/api/fluig/social/v1/communities/{id}/users
- URL com suporte a campos expansíveis
- https://totvs.com/api/fluig/fdn/v1/users/{alias}?expand=prop1.subprop,prop2
- Ordenando e paginando coleções
...
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. Apesar de não definirmos uma estrutura única com uma série de regras para esses agrupamentos (já que não conseguimos generalizar todas as linhas de negócio) Usamos como base a estrutura {dominio}/api/{produto}/{modulo}/{versão}/. 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.
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com/api/fluig/ecm/v1/documents GET http://totvs.com/api/fluig/bpm/v1/workflows GET http://totvs.com/api/fluig/lms/v1/classes |
Formatos de Data
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?order=name,-age,surname |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?name=john&surname=doe |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?page=4&pageSize=10 |
...
| 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 |
...
| 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 onde a nova entidade poderá ser encontrada. Por exemplo, considere o endpoint de cadastro assíncrono de usuários:
DEVE retornar como responta:
|
Como escolher o método adequado
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/1
{
name: "John",
sobrenome: "Doe"
} |
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10 { _expandables: ["permissions"], name: "John", sobrenome: "Doe", age: 18, country: US, permissions: {} } |
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age
{
name: "John",
age: 18
} |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10
{
_expandables: ["permissions", "communities", "detailedInformation"]
id: 10
name: "Usuário"
age: 25
permissions: []
communities: []
detailedInformation: { }
} |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities
{
_expandables: ["permissions", "detailedInformation"]
id: 10
name: "Usuário"
age: 25
permissions: []
communities: [
{
_expandables: ["permissions"],
name: "Vendas",
photoUrl: "https://totvs.com/communities/1/photo",
permissions: {}
},
{
_expandables: ["permissions"],
name: "Outra comunidade",
photoUrl: "https://totvs.com/communities/2/photo",
permissions: {}
}
]
detailedInformation: { }
} |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities.permissions { _expandables: ["permissions", "detailedInformation"] id: 10 name: "Usuário" age: 25 permissions: [] communities: [{ name: "Vendas", photoUrl: "https://totvs.com/communities/1/photo", permissions: { isAdmin: true, canView: true } }, { name: "Outra comunidade", photoUrl: "https://totvs.com/communities/2/photo", permissions: { isAdmin: true, canView: true } }] detailedInformation: { } } |
...
| 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 "minor":
- 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 "minor":
- 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.
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas