Paginação e cursores

01Em uma frase #sec_4400178a

Todas as listas da API são percorridas por cursor, nunca por número de página — e o cursor é opaco: sua forma não é um contrato, seu uso é.

02O envelope de resposta #sec_95dbbbe4

Todo ponto de chamada que retorna uma lista retorna o mesmo envelope: os dados de um lado, a posição do outro.

{
  "data": [ ... ],
  "page": {
    "limit": 100,
    "nextCursor": "YzE6NDIx"
  }
}

data carrega os elementos. page.limit lembra o tamanho efetivamente aplicado — que nem sempre é o solicitado, veja mais abaixo. page.nextCursor carrega a posição a ser retomada, ou null quando não há mais nada depois.

03Percorrer #sec_6f1e95f9

A primeira chamada não carrega um cursor. Cada uma das seguintes retoma o nextCursor da anterior.

GET /api/v1/campaigns?limit=100
GET /api/v1/campaigns?limit=100&cursor=YzE6NDIx
GET /api/v1/campaigns?limit=100&cursor=YzE6Mzgy

O ciclo para em nextCursor: null, não numa página incompleta. Uma página pode retornar menos elementos que o limite solicitado sem ser a última; parar neste sinal faria com que o restante fosse perdido, silenciosamente.

04O limite #sec_f8bab3ec

Cem elementos por padrão, quinhentos no máximo. Um valor fora dos limites não é recusado: ele é trazido de volta aos limites, e page.limit diz então o que foi realmente aplicado.

É por isso que page.limit está na resposta: sem ele, um cliente que solicita 5000 acreditaria ter recebido tudo.

05O cursor é opaco #sec_1c8cde92

O cursor é uma cadeia. O que ele codifica é um detalhe de implementação que pode mudar sem aviso prévio, e decodificá-lo para fabricar outro é a maneira mais segura de quebrar sua integração na próxima versão.

Duas regras são suficientes: retomar aquele que a resposta anterior deu, tal qual; nunca construir um.

Um cursor mal formado ou adulterado não é um erro: ele é tratado como uma ausência de cursor, e o percurso recomeça do início. Uma integração que fabricasse seus cursores, portanto, giraria em círculos na primeira página sem que nada o indicasse.

06A ordem do percurso #sec_3157b042

A ordem é estável e decrescente no identificador: os elementos mais recentes primeiro. É isso que torna o percurso seguro — um elemento adicionado enquanto você pagina aparece antes da sua posição, portanto não desloca o que resta a ser lido e você não o verá duas vezes.

A contrapartida é franca: um percurso longo não vê o que chegou depois do seu primeiro chamado. Para recuperar o recente, reinicie um percurso desde o início em vez de continuar o antigo.

07Retomar mais tarde #sec_98015cd3

Um cursor permanece utilizável além da vida do token que o produziu: renovar o token não obriga a recomeçar o percurso. Conserve a posição, não a sessão.

08A reter #sec_35ad77bf

Um envelope único para todas as listas. Um limite entre 1 e 500, reduzido nos limites e lembrado na resposta. Um cursor que se retoma e que nunca se fabrica. E apenas uma condição de parada: nextCursor a null.