Pagination des API : comment parcourir une collection

Que signifie recevoir une collection paginée ?

Une collection paginée fournit ses résultats par parties, au lieu de les renvoyer tous ensemble dans une seule réponse. Pour la personne qui intègre le service, une lecture apparemment simple devient alors un parcours : il faut demander une partie, la traiter et déterminer, selon les règles du point de terminaison, s’il convient d’en demander une autre. Sensedia recommande d’utiliser la pagination pour les services qui renvoient de grandes quantités de données ; il s’agit d’une recommandation de cette source, et non d’une règle décrivant le fonctionnement de chaque API. Consultez la source : https://www.sensedia.com.es/post/api-buenas-practicas-de-paginacion-y-filtros.

Le mécanisme précis peut varier. La documentation du service peut décrire un signal de continuation, un paramètre ou une autre façon d’indiquer comment poursuivre ; ne choisissez pas l’une de ces possibilités par habitude. Avant de programmer, repérez trois éléments dans le contrat applicable : comment la lecture commence, quelles informations permettent de continuer et quelle condition indique qu’elle est terminée. S’il en manque un, clarifiez ce point avant de considérer une réponse comme une collection complète.

Il est utile de distinguer deux questions souvent confondues : « Ai-je reçu une réponse correcte ? » et « Ai-je parcouru toute la collection ? ». La première concerne l’appel que vous venez d’effectuer. La seconde exige de suivre la procédure décrite pour cette opération et d’atteindre sa condition de fin.

• Confirmez le comportement du point de terminaison concerné ; ne déduisez pas son mécanisme du nom de l’API.
• Recherchez à la fois le signal permettant de continuer et la condition documentée qui met fin au parcours.
• Considérez la recommandation de Sensedia comme une recommandation, et non comme une garantie concernant un service particulier.

Une procédure pratique, selon le contrat

Vous pouvez organiser l’implémentation sous la forme d’une boucle conceptuelle. Ce schéma ne prescrit ni nom de paramètre ni structure de réponse universelle : remplacez chaque élément par ce que prévoit la documentation technique du point de terminaison.

1. Définissez l’opération à consulter et consignez sa méthode, son point de terminaison et les paramètres initiaux requis. 2. Effectuez la requête initiale et traitez les résultats de cette réponse. 3. Examinez les informations de continuation décrites par le service. 4. Si ces informations indiquent qu’une partie suivante existe, préparez la requête suivante exactement comme le prévoit le contrat, puis traitez à nouveau ses résultats. 5. Ne mettez fin à la boucle que lorsque la condition de fin documentée par le service est remplie.

En pseudocode, l’idée est la suivante : « commencer selon le contrat ; tant que le contrat indique qu’il y a une suite, demander la partie suivante en utilisant le mécanisme documenté et traiter ses résultats ; s’arrêter lorsque le signal documenté indique la fin ». Ce pseudocode est volontairement abstrait et ne constitue pas une recette destinée à une API particulière. Ne construisez pas vous-même une URL, un numéro de page ou un curseur si le contrat ne précise pas que vous devez le faire.

Avant d’implémenter la boucle, notez quelle donnée concrète de la réponse est interprétée comme un signal de continuation et quelle valeur ou quel état marque la fin. Identifiez également ce qui doit être conservé d’une requête à l’autre, si le service le précise. Cette courte description permet à une autre personne de vérifier le flux et aide à repérer les erreurs d’interprétation sans attribuer au fournisseur des règles qu’il n’a pas publiées.

• Début : utilisez les paramètres initiaux documentés pour l’opération.
• Continuation : utilisez uniquement le signal et la procédure décrits pour ce point de terminaison.
• Fin : arrêtez-vous lorsque la condition publiée est remplie ; le fait qu’une réponse isolée semble contenir peu de résultats ne suffit pas.
• Si la documentation ne définit pas une étape, consignez la question et demandez une clarification au lieu d’inventer une règle.

Un exemple précis : New Relic REST API v2

La documentation de New Relic REST API v2 indique que, lorsque les données sont paginées, la réponse comprend un en-tête Link qui précise le nombre de pages et celle qui est consultée. C’est un exemple concret d’information documentée par un fournisseur pour son API ; cela ne prouve pas que d’autres services incluent le même en-tête et ne permet pas de transposer ce comportement à un autre point de terminaison. Consultez la documentation : https://docs.newrelic.com/es/docs/apis/rest-api-v2/basic-functions/pagination-api-output/.

Lorsque vous consultez cette référence, notez ce qu’elle indique au sujet de l’en-tête et comparez-le à l’opération que vous allez réellement utiliser. Les informations décrites indiquent le nombre total de pages et la page consultée. Ne partez pas du principe que vous savez comment construire la requête suivante simplement parce que vous connaissez cette donnée : suivez les instructions applicables de la documentation de New Relic pour cette opération.

Cet exemple montre également pourquoi il est utile de distinguer « un modèle possible » du « contrat de mon point de terminaison ». Si un fournisseur utilise un autre signal ou définit des conditions différentes, la boucle de votre intégration doit s’y adapter. Cet exemple sert à orienter la lecture de la documentation, et non de modèle universel.

• L’en-tête Link décrit dans la source concerne New Relic REST API v2.
• Vérifiez dans la documentation applicable comment poursuivre le parcours ; ne déduisez pas d’instructions supplémentaires à partir d’une donnée isolée.

Que vérifier si la lecture est interrompue ou si des enregistrements se répètent ?

Imaginez que le processus s’arrête après la réception de quelques parties, mais avant que la condition de fin soit atteinte. Ne marquez pas l’importation comme terminée simplement parce que des résultats ont déjà été enregistrés. Consignez que l’exécution a été interrompue et vérifiez, avant de la reprendre, ce que le contrat prévoit concernant la continuation. Vous ne pouvez pas supposer qu’une position ou un curseur sera conservé ou pourra être récupéré indéfiniment.

La reprise est un choix d’implémentation, et non une garantie générale de l’API. Si la documentation n’explique pas comment récupérer la progression après une interruption, demandez des précisions. Si elle l’explique, implémentez cette procédure et définissez comment distinguer une exécution terminée d’une exécution en attente. Évitez de présenter la dernière valeur observée comme un point de reprise valide si le service ne le prévoit pas.

Un autre cas pratique consiste à recevoir des enregistrements qui semblent se répéter lors du traitement de différentes parties. Ne les supprimez pas automatiquement et ne supposez pas que le service garantit l’absence de répétitions : comparez d’abord les identifiants disponibles, puis examinez le contrat et l’historique de l’exécution pour comprendre ce qui s’est passé. Si vous décidez que l’application doit traiter les identifiants répétés d’une manière précise, documentez cette règle comme un choix qui vous est propre et vérifiez qu’elle ne masque pas des données qui auraient dû être conservées.

Ces vérifications aident à diagnostiquer une exécution, mais ne garantissent pas à elles seules une lecture complète. La bonne stratégie dépend des règles du point de terminaison et des besoins de l’intégration ; les éléments disponibles ne justifient pas une stratégie universelle de reprise ou de déduplication.

• En cas d’interruption, conservez les informations de diagnostic et vérifiez si le mécanisme documenté permet de reprendre le parcours.
• En cas d’enregistrements répétés, comparez les identifiants et vérifiez comment ils ont été obtenus avant de décider de les écarter.
• Ne confondez pas une exécution qui a enregistré des données avec une exécution qui a atteint le signal de fin.

Contrôles pour vérifier le résultat

À titre de contrôles généraux d’ingénierie, vous pouvez consigner l’opération exécutée, ses dates et heures de début et de fin, le nombre de requêtes effectuées pendant le parcours et le signal interprété comme indiquant la fin. Ces données aident à comprendre le déroulement d’une exécution et à comparer une lecture à une autre. Elles ne constituent pas une preuve automatique d’intégrité, et leur niveau de détail doit être adapté à votre système.

Vous pouvez également vérifier les identifiants des éléments reçus et comparer le résultat à un décompte communiqué par le service, s’il en existe un. Considérez les écarts comme un indice à examiner, et non comme une conclusion immédiate : un décompte peut servir de référence, mais ne prouve pas à lui seul que tous les éléments attendus sont présents. De même, l’absence d’identifiants répétés ne prouve pas qu’aucun enregistrement ne manque.

Distinguez les informations communiquées par le service de celles calculées par votre propre intégration. Par exemple, précisez si un nombre provient d’une réponse documentée ou s’il correspond au total des éléments comptabilisés par votre processus. Vous éviterez ainsi de présenter une mesure locale comme une garantie du fournisseur et pourrez mieux localiser un écart.

• Consignez la condition de fin atteinte et les incidents survenus pendant le parcours.
• Examinez les écarts de décompte ou les identifiants répétés au lieu de les masquer automatiquement.
• N’utilisez un décompte de référence que si le service en fournit un, et ne le considérez pas comme une preuve complète d’intégrité.

Que vérifier dans une intégration avec Apification Cloud ?

Apification permet d’intégrer Cloud et ses services au moyen d’une REST API, d’OpenAPI, de webhooks, d’iframes et de JavaScript. Ces options décrivent des capacités d’intégration ; elles ne précisent pas à elles seules comment une opération particulière gère la pagination, ni quels paramètres, signaux de continuation ou garanties elle propose.

Si vous automatisez la lecture de ressources, appliquez la procédure générale seulement après avoir identifié le contrat technique de l’opération que vous allez utiliser. Notez le point de terminaison, la méthode de continuation documentée et la condition de fin. Si l’une de ces règles n’est pas disponible, l’intégration ne doit pas la remplacer par une convention inventée.

Apification Cloud permet d’organiser des fichiers, des services et des projets dans un espace versionné et partageable. Cette capacité ne signifie pas qu’un point de terminaison utilise un type de pagination donné. Distinguez les fonctionnalités de la plateforme des règles que doit définir la documentation du service consulté.

• Confirmez le mécanisme de continuation et la condition de fin dans la documentation technique correspondante.
• N’attribuez pas à Apification Cloud de mécanisme de pagination, de reprise ou de garantie d’intégrité sans documentation qui l’établisse.

Questions fréquentes