API - Guia de Estilo

Paginação, ordenação e filtros

1172 views 05/08/2020 14/10/2020 jefersonfrancisco 1

Paginação:

Endpoints que retornam coleções devem suportar a paginação dos resultados com o objetivo de obter melhor performance nas buscas. Uma busca endpoint que retorna uma coleção nunca deve retornar todos os itens. Os dados de paginação devem ser enviados pelos parâmetros de URL size e offset:

  • size:  identifica a quantidade de itens a ser obtido na página.
  • offset: Identifica a página de dados da coleção a ser obtida.

Exemplo: Offset inicia em 0 e o size padrão é 10. Neste caso, para retornar do primeiro registro ao quinto, informa-se offset=0&size=5. Para obter do sexto registro ao décimo, informa-se offset=1&size=5

REQUEST:
/listFoo?offset=0&size=5

Em endpoints de coleção, o corpo da mensagem de resposta deve obrigatoriamente retornar na raiz do JSON os campos:

  • totalPages: Total de páginas baseado na quantidade de registros passado no campo size
  • totalElements: Total de registros encontrados
  • contents: Lista de registros que foram encontrados na busca, deve ter a mesma quantidade de registros que foi passado no campo size

Exemplo de retorno com formato correto:

 {
   "totalPages" : 9,
   "totalElements" : 99,
   "contents" : [
     ...
   ]
 }

Filtros:

Endpoints que retornam coleções devem suportar filtros de busca. O(s) campo(s) que será utilizado(s) como filtro são definidos em cada API. Em Filtros que necessitam enviar grandes quantidades de registros e dados estruturados deve-se enviar uma requisição do tipo POST com os dados no corpo da mensagem. Isso se deve ao fato de a URL possuir limitação, mais detalhes podem ser consultados aqui.

Ordenação:

Endpoints que retornam coleções devem suportar ordenação dos registros na requisição. Para fazer uma requisição com ordenação, deve ser possivel adicionar o parâmetro orderby à URL, seguido de um sinal de =, e após um ou mais atributos do recurso pelo qual deseja-se fazer à ordenação:

GET http://api.senior.com.br/ecossistema/reference_app/entities/customer?orderby=id

Caso haja a necessidade de ordenação em ordem decrescente, basta adicionar um espaço em branco e o termo desc após o nome do atributo na url:

GET http://localhost:9090/bridge/rest/entidades/tutorial/entities/customer?orderby=teste+desc

Para utilizar mais de um atributo na ordenação, basta separá-los por vírgula:

GET http://localhost:9090/bridge/rest/entidades/tutorial/entities/customer?orderby=teste+desc,userid

ODATA

As entidades por padrão implementam o protocolo ODATA. O uso desse protocolo nas primitivas que o objetivo é a busca de algum dado, tem a implementação recomendada para manter o padrão de busca em nossas APIs. Detalhes de como utilizar os filtros ODATA podem ser encontrados em https://dev.senior.com.br/documentacao/uso-da-sdk-generica-de-entidades/tutorial-de-uso-das-apis-de-entidade-com-odata/

 

Este artigo foi útil para você?