Skip to main content

​
Visão geral da paginação

Alguns endpoints que retornam listas de recursos utilizam a paginação para facilitar a navegação em grandes volumes de dados. Com a paginação da API da Olie, você acessa conjuntos menores e mais fáceis de gerenciar, garantindo melhor desempenho e controle sobre os resultados retornados.
A paginação melhora a performance da API e facilita o processamento dos dados no lado do cliente.

​
Estrutura da resposta paginada

Respostas paginadas incluem um objeto meta com informações detalhadas sobre a paginação atual: 
{
  "...": [/** lista de itens retornados */],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 19,
    "per_page": 30,
    "to": 30,
    "total": 546
  }
}

​
Esquema do atributo meta

​
current_page
integer
Página atual da resposta. Começa em 1.
​
from
integer
Índice do primeiro item retornado na página atual (baseado em 1).
​
to
integer
Índice do último item retornado na página atual (baseado em 1).
​
last_page
integer
Número total de páginas disponíveis com base no total de itens e itens por página.
​
per_page
integer
Quantidade de itens retornados por página. Valor padrão é 30 e o máximo permitido é 100. Este valor reflete o parâmetro perPage utilizado na requisição (ou o padrão aplicado).
​
total
integer
Total geral de itens disponíveis na listagem, considerando todos os filtros aplicados.

​
Parâmetros de paginação

A paginação é controlada através de dois parâmetros de query que podem ser passados na URL via query params ou no payload de uma requisição POST:
​
page
integer
default:"1"
Número da página que deseja acessar. Deve ser um número inteiro maior ou igual a 1. Se não for fornecido ou for inválido, o padrão é 1.
​
perPage
integer
default:"30"
Quantidade de itens retornados por página. Deve ser um número inteiro entre 1 e 100. Se não for fornecido, o padrão é 30. Valores acima de 100 serão automaticamente limitados a 100.
Você pode combinar paginação com filtros para navegar através de subconjuntos específicos de dados.

​
Exemplos práticos

As consultas básicas GET aceitam paginação via query params, utilizando os parâmetros page e perPage. 
GET /api/management/projects
Retorna a primeira página com 30 itens (valores padrão).
Quando os endpoints suportam filtros complexos, você provavelmente vai querer utilizar o parâmetro filter no payload da sua requisição POST. Os parâmetros de paginação também podem ser incluídos no payload. 
POST /api/management/projects/search
{
  "page": 1,
  "perPage": 50,
  "filter": [/** array de filtros complexos */]
}
Quando os parâmetros page e perPage são fornecidos no payload de uma requisição POST, eles têm precedência sobre os parâmetros de query string, se houver.
Consulte a documentação de filtros para mais informações sobre como utilizar a busca avançada.

​
Boas práticas

1

Use paginação sempre

Nunca tente buscar todos os registros de uma só vez. Sempre use paginação para melhor performance.
2

Armazene o meta

Guarde as informações do objeto meta para implementar navegação inteligente.
3

Implemente cache

Considere implementar cache local para páginas visitadas muitas vezes e reduzir requisições.
Não assuma que o número de itens por página (per_page) será sempre o mesmo. Sempre use o valor retornado no objeto meta para garantir que sua aplicação funcione corretamente.

​
Validação e comportamento

A API valida automaticamente os parâmetros de paginação e aplica correções quando necessário:
  • page inválido (menor que 1 ou não numérico): será ajustado para 1
  • perPage inválido (menor que 1 ou não numérico): será ajustado para 30 (padrão)
  • perPage maior que 100: será limitado automaticamente a 100
Mesmo que você envie valores inválidos, a API sempre retornará uma resposta válida, aplicando os valores padrão ou limites quando necessário. O objeto meta na resposta sempre refletirá os valores efetivamente utilizados.

​
Exemplo de resposta completa

{
  "response": true,
  "data": [
    {
      "id": 1,
      "name": "Projeto A",
      "status": "ativo"
    },
    {
      "id": 2,
      "name": "Projeto B",
      "status": "concluido"
    }
    // ... mais 28 itens
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 19,
    "per_page": 30,
    "to": 30,
    "total": 546
  }
}
Com essas informações, você pode implementar uma navegação eficiente e intuitiva através dos dados da API!