Histórico da Página
...
| 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 |
...
Formato das mensagens de resposta
JSON deve ser o formato padrão para mensagens e as propriedades destas mensagens devem ser escritas usando camelCase..
Ao desenvolver uma API referente à mensagem padronizada, deve ser utilizado o padrão UpperCamelCase para as propriedades dessa mensagem.
Todos os endpoints devem suportar este tipo de conteúdo.
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/1
{
nameName: "John",
sobrenomeSurname: "Doe"
} |
| Âncora | ||||
|---|---|---|---|---|
|
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10
{
_expandables: ["permissionsPermissions"],
name Name: "John",
sobrenomeSurname: "Doe",
ageAge: 18,
countryCountry: US,
permissionsPermissions: {}
} |
Caso os únicos campos interessantes para o cliente sejam o "name" e "age" ele pode reduzir a quantidade de dados usando o parâmetro fields. Ex:
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age
{
name Name: "John",
ageAge: 18
} |
| Informações |
|---|
O parâmetro fields deve ter precedência sobre o parâmetro expand. Isso que dizer que o campo não será retornado a menos que esteja na lista de campos do parâmetro fields mesmo que ele esteja presente na lista de campos a serem expandidos do parâmetro expand. |
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10
{
_expandables: ["permissionsPermissions", "communitiesCommunities", "detailedInformationDetailedInformation"]
idId: 10
nameName: "Usuário"
ageAge: 25
permissionsPermissions: []
communitiesCommunities: []
detailedInformationDetailedInformation: { }
} |
Caso o cliente queira expandir as propriedades, ele 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.
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities
{
_expandables: ["permissionsPermissions", "detailedInformationDetailedInformation"] # refere-se aos atributos do objeto pai (1o nível)
idId: 10
nameName: "Usuário"
ageAge: 25
permissionsPermissions: [] # permissões do usuário
communitiesCommunities: [
{
_expandables: ["permissionsPermissions"], # refere-se ao atributo permissions deste objeto-filho (2o nivel)
nameName: "Vendas",
photoUrlPhotoUrl: "https://totvs.com/communities/1/photo",
permissionsPermissions: {} # permissões da comunidade 'Vendas'
},
{
_expandables: ["permissions"], # refere-se ao atributo permissions deste objeto-filho
nameName: "Outra comunidade",
photoUrlPhotoUrl: "https://totvs.com/communities/2/photo",
permissionsPermissions: {} # permissões da comunidade 'Outra comunidade'
}
]
detailedInformationDetailedInformation: { }
} |
Note que as propriedades do objeto expandido devem vir retraídas por padrão. O cliente 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:
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities.permissions
{
_expandables: ["permissionsPermissions", "detailedInformationDetailedInformation"]
idId: 10
nameName: "Usuário"
ageAge: 25
permissionsPermissions: []
communitiesCommunities: [{
nameName: "Vendas",
photoUrlPhotoUrl: "https://totvs.com/communities/1/photo",
permissionsPermissions: {
isAdminIsAdmin: true,
canViewCanView: true
}
}, {
nameName: "Outra comunidade",
photoUrlPhotoUrl: "https://totvs.com/communities/2/photo",
permissionsPermissions: {
isAdminIsAdmin: true,
canViewCanView: true
}
}]
detailedInformationDetailedInformation: { }
}
|
| 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
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas