Une pagination d’API doit définir la taille des pages, l’ordre, le curseur et le comportement des données ajoutées pendant la consultation.
Renvoyer toute une liste devient lent quand le volume augmente. La pagination limite la réponse et permet à l’interface de charger ce dont elle a besoin. Le contrat doit cependant empêcher les doublons et les omissions lorsque les données changent entre deux appels.
Choisir un ordre stable
Triez par une colonne déterministe, souvent une date accompagnée d’un identifiant unique. Une date seule peut contenir plusieurs lignes identiques. Le second critère permet de reprendre après le dernier élément sans ambiguïté.
Un tri demandé par l’utilisateur doit être contrôlé par une liste autorisée. Ne construisez pas une requête à partir d’un nom de colonne reçu sans validation. La spécification de contrat API doit documenter les tris disponibles.
Comparer offset et curseur
La pagination par offset est simple pour les petites listes et les pages numérotées. Elle peut devenir coûteuse quand le moteur doit parcourir de nombreuses lignes avant de retourner le résultat. Des insertions peuvent aussi déplacer les éléments entre deux pages.
Un curseur représente la position dans un ordre défini. Il est plus adapté aux flux et aux grandes listes, mais il doit avoir une durée de vie et un format documentés. Un curseur expiré doit produire une réponse claire qui permet de recommencer.
Gérer les limites
Imposez une taille maximale de page et une valeur par défaut raisonnable. L’utilisateur peut demander moins de lignes, mais ne doit pas contourner la limite avec un nombre arbitraire. Une limite protège la base et rend les temps de réponse plus prévisibles.
Ajoutez un indicateur de page suivante quand il est fiable. Évitez de promettre un nombre total de lignes si le calcul est coûteux ou si les droits changent pendant la lecture. Une interface peut continuer jusqu’à l’absence de résultat.
Tester les modifications concurrentes
Insérez une ligne entre deux appels et modifiez une ligne déjà lue. Vérifiez que l’ordre choisi produit le comportement annoncé. Les tâches différées et les permissions doivent utiliser le même filtre que la requête initiale.
Une pagination correcte se mesure avec les requêtes réelles, un volume représentatif et une base surveillée. Elle doit rester compatible avec les exports de données qui ont parfois besoin d’un traitement séparé.
Sources : Microsoft, pagination avec curseur, PostgreSQL, LIMIT et OFFSET.