Ressources · 86
Pagination d’API : terminer un export sans pertes ni doublons
Définir ordre, jetons, autorisations et reprise lorsque la collection change pendant sa lecture.
· 4 min
Ce que ce guide permet
- Définir ordre et périmètre
- Traiter le jeton comme une continuation
- Détecter la fin selon le contrat
- Reprendre après un échec
- Rapprocher le résultat
Contrôle express
- Une page vide signifie-t-elle la fin ?
- Peut-on utiliser un curseur comme autorisation ?
- Dédupliquer suffit-il pour éviter les pertes ?
Méthode pas à pas
- 01
Définir ordre et périmètre
Documentez filtre, ordre et clé de départage. Une date seule peut être insuffisante si plusieurs objets la partagent. Décidez si la collection reste vivante ou si l’export se rattache à un instantané. Ne promettez pas une vue figée si le fournisseur ne propose pas cette garantie.
Livrable : contrat d’ordre et de cohérence.
- 02
Traiter le jeton comme une continuation
AIP-158 prévoit des jetons opaques et distingue pagination et autorisation : le jeton ne confère pas de droit d’accès. Vérifiez l’identité et les permissions à chaque requête. Conservez les paramètres de la lecture selon le contrat, et traitez expiration ou invalidation comme un état explicite.
Livrable : cas de jeton valide, expiré et interdit.
- 03
Détecter la fin selon le contrat
Ne concluez pas à la fin parce qu’une page est plus courte que la taille demandée. Une API peut retourner moins d’éléments tout en fournissant une continuation. Selon AIP-158, un next_page_token vide indique la fin ; adaptez le client au contrat réel du fournisseur. Détectez aussi un jeton qui se répète sans progression.
Livrable : tests de fin et de boucle.
- 04
Reprendre après un échec
Enregistrez la continuation après conservation durable du lot traité. Dédupliquez avec des identifiants stables et gardez l’état de reprise distinct du total affiché. Si l’instantané expire, recommencez ou rapprochez selon une politique explicite ; ne concaténez pas discrètement deux collections différentes.
Livrable : point de reprise et scénario de panne.
- 05
Rapprocher le résultat
Comparez identifiants uniques, exclusions, états et éventuel total de référence à la même date. Testez création, modification et suppression pendant la lecture. Un compte d’objets correct ne prouve pas que ce sont les bons objets. Protégez fichiers et traces selon les données exportées.
Livrable : manifeste d’export et écarts documentés.
Une lecture paginée qui peut reprendre
Pour un contrat de type AIP-158, la continuation détermine la suite. Une page courte ne prouve pas la fin.
Fixer la lecture
Conserver filtre, ordre, paramètres et identité autorisée.
Conserver le lot
Enregistrer durablement les objets et leurs identifiants.
Suivre la continuation
Un jeton présent conduit à la requête suivante avec les paramètres liés.
Rapprocher à la fin
À jeton final vide, vérifier exclusions, état de référence et couverture.
Exemple fictif : la connexion échoue après conservation d’un lot. La reprise utilise le point enregistré et contrôle les identifiants déjà traités.
Fiche de travail à réutiliser
À compléter avec vos observations autorisées. Ces champs constituent une trame de travail, pas des résultats observés.
| Champ | Information à consigner |
|---|---|
| Collection | Filtres, ordre, clé de départage et garanties |
| Continuation | Jeton, paramètres liés, expiration et fin |
| Reprise | Lot durable, identifiants uniques et point enregistré |
| Résultat | Manifeste, exclusions, date et écarts de rapprochement |
Exemple d’application
Situation illustrative
Exemple fictif : un catalogue ajoute des produits pendant un export par offset. Une ligne se déplace entre deux pages.
Décision et preuve attendue
Le test repère une répétition et un produit absent ; l’équipe choisit un instantané proposé par l’API ou documente une lecture vivante avec rapprochement.
Distinguer les mécanismes
| Mécanisme | Utilité | Point de vigilance |
|---|---|---|
| Offset | Accéder à une position numérique | Les insertions peuvent déplacer les positions |
| Curseur | Continuer une lecture selon un repère | Ne garantit pas seul un instantané |
| Instantané | Fixer un état de référence | Vérifier durée de validité et coût |
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| Identifiants uniques | Objets distincts conservés dans l’export | Comparer à une référence de même périmètre |
| Progression | Jetons et lots qui avancent réellement | Arrêter les boucles et investiguer |
| Couverture vérifiée | Objets rapprochés avec l’état de référence | Ne pas confondre volume et exhaustivité |
Erreurs fréquentes
- Les insertions peuvent déplacer les positions
- Ne garantit pas seul un instantané
- Vérifier durée de validité et coût
Questions fréquentes
Une page vide signifie-t-elle la fin ?
Consultez le contrat et le jeton de continuation. La taille de page seule ne doit pas décider de la fin.
Peut-on utiliser un curseur comme autorisation ?
Non. Le serveur doit contrôler les droits de la requête indépendamment du jeton de pagination.
Dédupliquer suffit-il pour éviter les pertes ?
Non. Cela retire les répétitions mais ne récupère pas les objets jamais lus. Testez la stabilité de l’ordre et les changements de collection.
Références officielles
Date de consultation des références : . La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
Pour aller plus loin
Analyses associées
