Histórico da Página
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10
{
_expandables: ["Permissions"],
name: "John",
surname: "Doe",
age: 18,
country: US,
permissions: {}
} |
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:
...
Indicamos o uso de campos expansíveis para todos os endpoints que possuam subníveis, todavia sua aplicação deve ser precedida da análise da equipe de negócio e com vistas a usabilidade. E 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 obedecer as regras a seguir:
...
.
O campo _expandables é uma lista com o nome de cada uma das propriedades que podem ser passadas na url para que o endpoint inclua na resposta.
| Informações | ||
|---|---|---|
| ||
| A técnica de parâmetros expansíveis se aplica a todos os verbos HTTP onde o corpo contenha estruturas passíveis de retração (listas ou objetos). Por exemplo, se num endpoint usando POST o retorno contenha, no corpo, um objeto contendo uma lista, esta deve vir retraída e o atributo deve constar no parâmetro _expandables. |
...
| 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
permissionsid: []10
communitiesname: []"Usuário"
detailedInformationage: { }25
} |
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.
| Nota | ||
|---|---|---|
| ||
Apenas o primeiro nível das propriedades deve ser expandido, ou seja, se o objeto expandido tiver propriedades expansíveis elas devem vir retraídasnão serão retornadas. |
Por exemplo, no cenário em que o cliente gostaria de expandir as comunidades da entidade usuário:
| Bloco de código | ||
|---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities
{
_expandables: ["permissions", "detailedInformation"] # refere-se aos atributos do objeto pai (1o nível)
id: 10
name: "Usuário"
age: 25
permissions: [] # permissões do usuário
communities: [
{
_expandables: ["Permissions"], # refere-se ao atributo permissions deste objeto-filho (2o nivel)
name: "Vendas",
photoUrl: "https://totvs.com/communities/1/photo",
permissions: {} # permissões da comunidade 'Vendas'photoUrl: "https://totvs.com/communities/1/photo"
},
{
_expandables: ["permissions"], # refere-se ao atributo permissions deste objeto-filho
name: "Outra comunidade",
photoUrl: "https://totvs.com/communities/2/photo",
permissions: {} # permissões da comunidade 'Outra comunidade'
}
]
detailedInformation: { }
} |
Note que as propriedades do objeto expandido devem vir retraídas não são retornadas 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: ["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: { }
}
|
| 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