Paginação

O que é

A paginação permite recuperar grandes coleções em respostas delimitadas. Os endpoints de listagem da YCloud usam paginação por número de página ou por cursor.

Antes de começar

Consulte a referência do endpoint para verificar os parâmetros de paginação compatíveis, filtros, ordem de classificação e o formato da resposta. Não presuma que todos os endpoints de listagem utilizam a mesma estratégia.

Como funciona

Solicite uma página, processe seus itens e continue até que a resposta indique que não há uma próxima página. Mantenha os mesmos filtros e configurações de classificação durante toda a varredura.

Requisição e resposta

Paginação por número de página

A maioria dos endpoints de listagem aceita estes parâmetros de consulta:

Parâmetro	Descrição
`page`	Número da página. Começa em `1` e tem como padrão `1`.
`limit`	Resultados por página. Varia de `1` a `100` e tem como padrão `10`.
`includeTotal`	Defina como `true` para incluir o número total de itens correspondentes.

curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"

A resposta de uma página contém:

{
  "offset": 0,
  "limit": 100,
  "length": 2,
  "total": 2,
  "items": [{ "id": "ITEM_1" }, { "id": "ITEM_2" }]
}

Campo de resposta	Significado
`items`	Objetos retornados nesta página.
`offset`	Posição inicial baseada em zero: `(page - 1) * limit`.
`limit`	Tamanho de página solicitado.
`length`	Número real de itens, igual a `items.length` e não superior a `limit`.
`total`	Total de itens correspondentes; retornado apenas quando `includeTotal=true`. Fazer a contagem pode adicionar latência, portanto solicite apenas quando necessário.

Endpoints baseados em deslocamento (offset) normalmente limitam tanto page quanto limit em 100, limitando a varredura aos primeiros 10.000 itens. Verifique os limites de cada endpoint e use paginação por cursor quando houver suporte e você precisar de um conjunto maior de resultados.

Continue solicitando a próxima página enquanto length for igual a limit. Pare quando length for menor que limit.

Paginação por cursor

Endpoints que retornam cursor.after têm suporte a paginação por cursor. Passe esse valor como pageAfter na próxima requisição.

curl "https://api.ycloud.com/v2/unsubscribers?limit=100&pageAfter=id%3Afoo" \
  --header "X-API-Key: $YCLOUD_API_KEY"

Uma resposta de cursor contém items, limit, length e, quando existirem mais resultados, cursor.after. O objeto de cursor é retornado apenas por endpoints compatíveis com paginação por cursor.

{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}

Envie o cursor retornado sem alterações para a próxima requisição. Trate-o como opaco; não o modifique nem o armazene como um identificador de longo prazo da aplicação. Pare quando length for 0 ou se a resposta não contiver mais cursor.after.

Os parâmetros de paginação e filtro variam conforme o endpoint. Consulte a referência da API antes de implementar uma operação de listagem.

Checklist de implementação

Defina um limit explícito em vez de depender do padrão.
Mantenha os filtros entre as requisições de página.
Interrompa com base na condição da resposta, e não em uma estimativa da contagem de páginas.
Trate uma primeira página vazia como um resultado bem-sucedido.
Adicione um limite de segurança de páginas ou itens máximos para tarefas em segundo plano.

Primeiros passos

Guias

Endpoints

Webhooks

O que é

Antes de começar

Como funciona

Requisição e resposta

Paginação por número de página

Paginação por cursor

Checklist de implementação

​O que é

​Antes de começar

​Como funciona

​Requisição e resposta

​Paginação por número de página

​Paginação por cursor

​Checklist de implementação

O que é

Antes de começar

Como funciona

Requisição e resposta

Paginação por número de página

Paginação por cursor

Checklist de implementação