Pagination et curseurs

01En une phrase #sec_4400178a

Toutes les listes de l'API se parcourent au curseur, jamais au numéro de page — et le curseur est opaque : sa forme n'est pas un contrat, son usage l'est.

02L'enveloppe de réponse #sec_95dbbbe4

Tout point d'appel qui rend une liste rend la même enveloppe : les données d'un côté, la position de l'autre.

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

data porte les éléments. page.limit rappelle la taille effectivement appliquée — qui n'est pas toujours celle demandée, voir plus bas. page.nextCursor porte la position à reprendre, ou null quand il n'y a plus rien après.

03Parcourir #sec_6f1e95f9

Le premier appel ne porte pas de curseur. Chacun des suivants reprend le nextCursor du précédent.

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

La boucle s'arrête sur nextCursor: null , pas sur une page incomplète. Une page peut rendre moins d'éléments que la limite demandée sans être la dernière ; s'arrêter sur ce signal ferait manquer la suite, silencieusement.

04La limite #sec_f8bab3ec

Cent éléments par défaut, cinq cents au maximum. Une valeur hors bornes n'est pas refusée : elle est ramenée dans les bornes, et page.limit dit alors ce qui a réellement été appliqué.

C'est pourquoi page.limit figure dans la réponse : sans lui, un client qui demande 5000 croirait avoir tout reçu.

05Le curseur est opaque #sec_1c8cde92

Le curseur est une chaîne. Ce qu'elle encode est un détail d'implémentation qui peut changer sans préavis, et le décoder pour en fabriquer un autre est la façon la plus sûre de casser son intégration à la prochaine version.

Deux règles suffisent : reprendre celui que la réponse précédente a donné, tel quel ; ne jamais en construire un.

Un curseur mal formé ou trafiqué n'est pas une erreur : il est traité comme une absence de curseur, et le parcours repart du début. Une intégration qui fabriquerait ses curseurs tournerait donc en rond sur la première page sans que rien ne le signale.

06L'ordre de parcours #sec_3157b042

L'ordre est stable et décroissant sur l'identifiant : les éléments les plus récents d'abord. C'est ce qui rend le parcours sûr — un élément ajouté pendant que vous paginez apparaît avant votre position, donc il ne décale pas ce qui reste à lire et vous ne le verrez pas deux fois.

La contrepartie se dit franchement : un parcours long ne voit pas ce qui est arrivé après son premier appel. Pour rattraper le récent, relancez un parcours depuis le début plutôt que de continuer l'ancien.

07Reprendre plus tard #sec_98015cd3

Un curseur reste utilisable au-delà de la vie du jeton qui l'a produit : renouveler le jeton n'oblige pas à recommencer le parcours. Conservez la position, pas la session.

08À retenir #sec_35ad77bf

Une enveloppe unique pour toutes les listes. Une limite entre 1 et 500, ramenée dans les bornes et rappelée dans la réponse. Un curseur qu'on reprend et qu'on ne fabrique jamais. Et une seule condition d'arrêt : nextCursor à null .