Histórico da Página

...

GET https://fluig.totvs.com.br/api/users?order=name,-age,surname

Filtros

As coleções podem suportar filtro e deve usar as técnicas abaixo de acordo com a complexidade exigida pela função:

Filtros simples

Filtros simples devem usar parâmetros de query que suportarem filtro devem suportar parâmetros no formato propriedade=filtro e as propriedades suportadas e como elas serão interpretadas devem estar listadas na documentação do endpoint. Ex:

GET https://fluig.totvs.com.br/api/users?name=john&surname=doe//fluig.totvs.com.br/api/users?name=john&surname=doe

Filtros complexos

Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4.

Filtros como ações

Além das opções acima é possível definir um filtro como uma ação e usar o método POST. Neste caso a url deve seguir as boas praticas para não poluir as URIs da API.

Paginação

Todos os endpoints de coleção devem suportar paginação. A definição de como a coleção deve ser paginada é definida pelos parâmetros de url page e pageSize respeitando as seguintes regras:

...

• O parâmetro pageSize é opcional e na sua ausência deve ser considerado usado o valor padrão definido pela linha de negócio do endpoint (20 por exemplo). Não devem ser retornados todos os registros da consulta;

• Os parâmetros de paginação devem obedecer a semântica de multiplicador, ou seja, se o cliente solicitou page=2 com um pageSize=20 deve-se retornar os registros de 21 até 40;

...

Para todas as mensagens que representam um erro (códigos HTTP 4xx e 5xx) deve-se retornar obrigatoriamente os campos a seguir:

{{
    code: "Código identificador do erro",
    helpUrlcode: "link para a documentaçãoCódigo identificador do errorerro",
    message message: "Literal no idioma da requisição descrevendo o erro para o cliente",
    detailedMessage: "Mensagem técnica e mais detalhada do erro"
}

...

• O campo helpUrl deve apontar diretamente para documentação do erro na API;O campo message deve descrever o erro de forma não técnica e pode ser usado pelos clientes para exibição ao usuário. O texto deste campo deve respeitar o idioma usado na requisição (definido pelo cabeçalho Accept-Language ou o padrão caso este não seja especificado). Além disso leve em consideração:
  • Não assuma que o usuário é um especialista no uso da sua API. Usuário podem incluir desenvolvedores, profissionais de TI, administradores e usuários finais;
  • Não assuma que o usuário saiba qualquer coisa sobre a implementação da função sendo exposta pelo endpoint;
  • Quando possível a mensagem deve ser construida de forma que um usuário técnico possa responder ao erro e corrigi-lo;
  • Mantenha a mensagem sucinta e, se necessário, inclua um link para a documentação de como corrigi-la.

• O campo detailedMessage deve descrever o erro de forma mais técnica e pode conter referências que ajudem na correção / localização do erro no contexto do servidor do fluig.
  
  

Opcionalmente pode-se retornar os campos:

• helpUrl: link para a documentação do error;
• details: Uma lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.

Exemplo:

...