Páginas filhas
  • Guia de implementacao das APIs TOTVS

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Comentário: Ajustes relativos ao uso do _expandables em POST e PUT. Incremento de alguns exemplos.

...

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
languagejs
{
  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
languagejs
{
  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
titleVerbos HTTP x parâmetros expansíveis
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
languagejs
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: { }
}

...