Paginação

Os endpoints que retornam listas entregam os resultados em páginas. Esta página mostra como pedir uma página com page e perPage e como ler o objeto meta da resposta para saber quantas páginas e quantos itens existem. Os filtros que você pode combinar com a paginação estão em Filtros básicos e Busca avançada. As regras desta página valem para as listagens que devolvem o objeto meta. Alguns endpoints paginam de outro jeito:

POST /api/management/search-activities, do registro de alterações, usa offset e devolve 10 registros por vez.
GET /api/management/marketplace/templates usa per_page, com padrão de 15 itens, e devolve os dados da paginação em pagination.
Os assistentes de etapa trazem os campos de paginação na raiz da resposta, como mostra a estrutura da resposta paginada.

Parâmetros de paginação

Dois parâmetros controlam a paginação. Nas listagens GET, envie os parâmetros na URL. Nas buscas POST, como a busca avançada, você também pode enviá-los no corpo da requisição.

integer

default:"1"

Número da página. Aceita inteiros a partir de 1. Se o valor estiver ausente ou for inválido, a API usa 1.

integer

default:"30"

Quantidade de itens por página, de 1 a 100. Se o valor estiver ausente, a API usa 30. Para valores acima de 100, a API usa 100.

Estrutura da resposta paginada

A resposta paginada traz a lista de itens e um objeto meta com os dados da paginação. O nome da lista depende do endpoint: projects na listagem de projetos, goals na listagem de metas, e assim por diante.

{
  "response": true,
  "projects": [
    { "id": "019b140c-235d-73ee-96df-3d2afbf7d13d", "code": "P-80", "name": "Implantação do CRM" },
    { "id": "019b140b-e38e-7207-8016-9bfe6fa1d02f", "code": "P-79", "name": "Treinamento da equipe comercial" }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 19,
    "per_page": 30,
    "to": 30,
    "total": 546
  }
}

O exemplo mostra só dois projetos, com poucos campos. Uma resposta real traz os 30 projetos da página, com todos os campos.

Campos do objeto `meta`

O objeto meta descreve a página retornada e o total da listagem.

integer

Página retornada. Começa em 1.

integer

Posição do primeiro item da página na listagem completa, contando a partir de 1.

integer

Posição do último item da página na listagem completa, contando a partir de 1.

integer

Número da última página, calculado a partir de total e per_page.

integer

Quantidade de itens por página. Reflete o perPage enviado na requisição ou o padrão aplicado (30). O máximo é 100.

integer

Total de itens da listagem, já com os filtros aplicados.

Três endpoints de assistentes de etapa são exceção. Neles, os campos de paginação (current_page, per_page, total e os demais) vêm na raiz da resposta, ao lado de data, e não dentro de meta: GET /api/management/step-assistants, GET /api/management/steps/{step}/assistants e GET /api/management/steps/{step}/assistants/execution-logs.

Exemplos

Os exemplos usam a listagem de projetos e a listagem de metas, que aceitam page e perPage na URL.

Pedir uma página pela URL

Esta requisição completa, com autenticação, pede a segunda página da listagem de projetos com 50 itens por página:

curl -H "Authorization: Bearer {{token_de_acesso}}" \
  "https://api.olie.ai/api/management/projects?page=2&perPage=50"

As variações abaixo mostram o efeito de cada parâmetro.

Primeira página (padrão)
Página específica
Itens por página
page e perPage juntos
Com filtro básico

GET /api/management/projects

Retorna a primeira página com 30 itens (valores padrão).

GET /api/management/projects?page=5

Retorna a página 5 com 30 itens por página.

GET /api/management/projects?perPage=50

Retorna a primeira página com 50 itens por página.

GET /api/management/projects?page=2&perPage=50

Retorna a página 2 com 50 itens por página.

GET /api/management/goals?page=2&perPage=20&filter[status]=active

Retorna a página 2 das metas ativas, com 20 itens por página. Os filtros aceitos variam por endpoint: confira na referência de cada um.

Paginar uma busca avançada

Na busca avançada, os filtros vão no array filters do corpo de uma requisição POST. Envie page e perPage no mesmo corpo:

POST /api/management/projects/search
Content-Type: application/json

{
  "filters": [
    { "field": "budget", "operator": "greater_than", "value": 10500 }
  ],
  "page": 1,
  "perPage": 50
}

Se você enviar page e perPage no corpo de uma requisição POST e também na URL, a API usa os valores do corpo. A estrutura dos filtros está em Busca avançada.

Validação dos parâmetros

A API corrige os valores de page e perPage fora do intervalo em vez de devolver erro:

Valor enviado	Valor usado pela API
`page` menor que 1 ou não numérico	1
`perPage` menor que 1 ou não numérico	30 (padrão)
`perPage` maior que 100	100

A resposta continua válida, e o objeto meta mostra os valores que a API usou de fato.

Percorrer todas as páginas

Para ler uma listagem inteira, peça uma página por vez e use o meta de cada resposta para decidir o próximo passo:

Avance enquanto houver páginas. Aumente page até current_page ser igual a last_page.
Leia o tamanho da página no meta. Use o per_page da resposta, não o valor que você enviou, porque a API pode ter ajustado o valor.
Guarde em cache as páginas mais consultadas, se a sua integração lê as mesmas páginas muitas vezes. Isso reduz o número de requisições.

Páginas relacionadas

Estas páginas complementam a paginação:

Estrutura de respostas: o formato comum das respostas de sucesso e de erro.
Filtros básicos: filtros filter[campo] na URL.
Busca avançada: filtros e ordenação no corpo de requisições POST.

Introdução

Geral

Referência da API

Parâmetros de paginação

Estrutura da resposta paginada

Campos do objeto `meta`

Exemplos

Pedir uma página pela URL

Paginar uma busca avançada

Validação dos parâmetros

Percorrer todas as páginas

Páginas relacionadas

​Parâmetros de paginação

​Estrutura da resposta paginada

​Campos do objeto meta

​Exemplos

​Pedir uma página pela URL

​Paginar uma busca avançada

​Validação dos parâmetros

​Percorrer todas as páginas

​Páginas relacionadas

Parâmetros de paginação

Estrutura da resposta paginada

Campos do objeto `meta`

Exemplos

Pedir uma página pela URL

Paginar uma busca avançada

Validação dos parâmetros

Percorrer todas as páginas

Páginas relacionadas