Pagination API : définition, curseur, next link et pièges
La pagination API consiste à récupérer une grande liste en plusieurs réponses : page 1, page 2, ou curseur suivant. GitHub documente l’usage de la pagination dans son API REST et MDN rappelle que l’en-tête HTTP Link peut transporter plusieurs liens.
Deux modèles fréquents
Avec une pagination par page, vous appelez ?page=2. Avec un curseur, l’API renvoie un jeton next_cursor. Le curseur est souvent préférable pour des listes qui changent vite, mais il peut expirer. Il ne faut pas le traiter comme une promesse magique.
Attention au lien suivant
Un next fourni par API doit être validé : même hôte attendu, schéma HTTPS, pas de redirection vers un domaine inconnu. Ne suivez pas aveuglément une URL injectée dans une réponse si le connecteur manipule des données non fiables.
Checkpoint
En automatisation, enregistrez le checkpoint après avoir traité avec succès la page, pas avant. Si vous sauvegardez le curseur avant traitement et que le workflow plante, vous sautez des données. Si vous le sauvegardez après chaque page réussie, la reprise est propre.
Exemple
Workflow : appeler page, traiter items, compter erreurs partielles, sauvegarder cursor, passer à la page suivante. Si une page échoue, relancez depuis le dernier cursor validé.
Compter les éléments
Ne faites pas confiance à une estimation globale si l’API change pendant l’import. Le total annoncé au début peut varier si des éléments sont ajoutés ou supprimés. Votre script doit surtout savoir combien d’items il a réellement traités et quel est le dernier curseur validé.
Arrêt propre
Définissez une limite de sécurité : nombre maximal de pages, durée maximale, domaine autorisé pour le lien suivant. Si le même curseur revient deux fois, stoppez et alertez. Une boucle de pagination infinie peut consommer un quota entier en quelques minutes.
Pagination et déduplication
Quand les données changent pendant l’import, un même élément peut apparaître sur deux pages ou disparaître entre deux appels. Ajoutez une déduplication par identifiant d’objet, pas seulement par numéro de page. La pagination organise le transport, elle ne garantit pas l’unicité métier.
Tests à faire
Testez trois situations : une liste vide, une seule page, plusieurs pages avec échec au milieu. Ces essais valident le mécanisme de reprise ; les autorisations, les quotas et les changements de données restent à contrôler avant la production.
Reconnaître la dernière page
Le signal de fin est défini par l’API : absence de lien suivant, curseur vide ou indicateur dédié. Une page plus courte que prévu n’est pas universellement la dernière. Suivez le contrat documenté plutôt qu’une hypothèse sur le nombre de résultats.
Avec un offset, une insertion en tête de liste entre deux appels peut déplacer les éléments et provoquer une répétition ou un oubli. Un curseur peut limiter ce problème, mais il ne garantit pas à lui seul une photographie immuable des données. Conservez les identifiants récupérés et utilisez les possibilités de tri ou de filtre temporel proposées par le service.
Reprendre sans sauter d’éléments
Un checkpoint doit inclure les filtres utilisés et l’état de traitement de la page. En cas d’échec partiel, ne passez à la suite que si les éléments non traités sont enregistrés pour une reprise explicite. Si le curseur a expiré, il faudra parfois recommencer la lecture puis dédupliquer ; enregistrer le curseur ne garantit pas sa validité future.
Sources
- docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
- developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link