Filtros e paginação

Ao fazer uma requisição nas APIs, alguns endpoints podem retornar um volume considerável de dados. Nesses casos é recomendado o uso de filtros e paginação para limitar as informações retornadas e para que a consulta na API não fique sobrecarregada.

Veja abaixo os exemplos de utilização desses recursos para suas requisições nas nossas APIs.

Paginação

A paginação permite uma navegação entre as listas de resposta de uma requisição de API. No entanto, para utilizar a paginação primeiro você deve conferir se na resposta da API desejada há paginação.

Há duas formas de você conferir se um endpoint possui paginação:

• No Headers do response:
  Uma API possui paginação se no Headers do response há o campo KEY X-Pagination. Esse campo indica o total de páginas (total_pages), o número total de itens retornados (total_count), o número da página atual (current_page), e se há pagina anterior (prev_page) ou posterior (next_page) a página atual. Os campos prev_page e next_page são do tipo booleano, e podem receber true ou false para indicar que há ou não uma página próxima.
  Veja na imagem a seguir uma Header com paginação:

• No query params:
  Os endpoints que permitem paginação possuem o parâmetro page em QUERY PARAMS, como o endpoint mapeamentos.

Depois de conferir se a resposta da API possui paginação, você pode utilizar o parâmetro page para acessar uma página específica.

Filtros

Os filtros disponíveis dependem dos endpoint que deseja filtrar. Cada _endpoint _possui filtros próprios que podem ser consultados nos QUERY PARAMS das referências de API. Vamos exemplificar um uso de filtros com a API de pedidos, para filtrar pedidos com filtro de data.

Por exemplo, para filtrar os pedidos pedidos que tiveram alteração de status no ano de 2021. Nesse caso precisamos filtrar as respostas das requisições da chamada /get/api -v2-orders utilizando os parâmetros start (para delimitar a data de início) e finish (para delimitar o data final). Note que os parâmetros star e finish seguem o modelo YYYY-MM-DD, em que YYYY deve ser preenchido por ano, MM pelo mês, e DD pelo dia. Nesse exemplo a requisição na API será:

<http://www.lojateste.com.br/api/v2/orders/?start=2022-01-01&finish=2022-12-31>

Note que o filtro é feito na URL em ?start=2021-01-01&finish=2021-12-31.

📘

Confira mais filtros e _endpoints _na nossa Referência de API.