Histórico da Página
...
JSON deveser o formato padrão para mensagensmensagens
| Informações | ||
|---|---|---|
| ||
Uma exceção seria o caso de desenvolver uma API referente à mensagem padronizada, devendo ser utilizado o padrão UpperCamelCase para as propriedades dessa mensagem. Esse padrão respeita o protocolo pré-definido da mensagem padronizada. |
Ao desenvolver uma API referente à mensagem padronizada, deve ser utilizado o padrão UpperCamelCase para as propriedades dessa mensagem.
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/1
{
Namename: "John",
Surnamesurname: "Doe"
} |
| Âncora | ||||
|---|---|---|---|---|
|
...
| Bloco de código | ||
|---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10
{
_expandables: ["Permissions"],
Name name: "John",
Surnamesurname: "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: ["Permissions"], # 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
...
| 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.
e as propriedades destas mensagens devem ser escritas usando camelCase..
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas