Histórico da Página
...
Todos as transações de informação que suportam campos do tipo data/hora, tanto no corpo das mensagens quanto na URI, devem usar um dos seguintes formartosformatos:
- Data UTC estendido (E8601DZw.d): yyyy-mm-ddThh:mm:ss.nnnnnn+|-hh:mm
- Data (E8601DAw.): yyyy-mm-dd
- Hora (E8601TMw.d): hh:mm:ss.ffffff
...
Mensagens de sucesso (código http 2xx devem) devem retornar diretamente a entidade que representa o objeto resultado resultante da operação do endpoint. Ex:
...
Bloco de código | ||
---|---|---|
| ||
{ hasNext: true, items: [ {}, {}, ... ] } |
Está A estrutura acima é a estrutura mínima esperada para respostas de coleção. Entretanto, porém, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. ExPor exemplo:
Bloco de código | ||
---|---|---|
| ||
{ totvs_transaction_id: 1, total: 100, hasNext: true, items: [ {}, {}, ... ] } |
Observe que na estrutura acima, os atributos totvs_transaction_id e total foram adicionados ao objeto de resposta, enquanto os atributos hasNext e items foram mantidos.
Mensagens de sucesso DELETE
Por padrão, nas mensagens de DELETE, o response a resposta deve ser enviadas enviada com Http HTTP Code 204 (No content) e sem corpo no retorno.
Caso a regra de negócio necessitar de um retorno com conteúdo, este deve ser enviado vir com Http HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.
Código 4xx versus 5xx
Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.
...
As entidades de retorno devem obedecer as regras a seguir:
- Todas as propriedades que representam listas devem vir retraídas por padrão e devem usar a notação de lista vazia (Ex.: [] ).
- Todas as propriedades que representam objetos devem vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )
- Ao retornar uma entidade, todas as suas propriedades que representam um objeto ou coleção devem vir retraídas e a entidade deve conter um campo adicional com o nome _expandables. Esse campo é 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. |
Por exemplo, Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas devem estar retraídas:
...
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' }, { _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: { } } |
...