Parcourir les aide-mémoire · API

Technologie: APICatégorie: Conception d’APINiveau: IntermédiaireMis à jour

Modèles de pagination d’API

Concevez et consommez des API paginées en toute sécurité grâce aux modèles offset, numéro de page, curseur, keyset et jeton de continuation, avec un ordre clair, un parcours stable et un comportement client sûr en production.

Sur cette page
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Pagination avec limite seule
  5. 2. Pagination par offset
  6. 3. Pagination par numéro de page
  7. 4. Renvoyer des métadonnées de pagination
  8. 5. Prudence avec les totaux
  9. 6. Pagination par curseur
  10. 7. Rendre les curseurs opaques pour les clients
  11. 8. Le contenu d’un curseur peut encoder l’état du tri
  12. 9. Pagination keyset
  13. 10. Utiliser un critère de départage déterministe
  14. 11. Aligner le prédicat keyset sur le sens du tri
  15. 12. Pagination keyset composite
  16. 13. Ne pas exposer les offsets de lignes de la base de données comme curseur métier stable
  17. 14. La pagination par offset peut sauter des lignes lors d’insertions concurrentes
  18. 15. La pagination par offset peut dupliquer des lignes lors de suppressions
  19. 16. La pagination keyset est généralement plus stable pour un parcours vers l’avant
  20. 17. La pagination par curseur ne crée pas automatiquement un instantané
  21. 18. Ajouter une borne supérieure stable pour les parcours longs
  22. 19. Pagination par jeton de continuation
  23. 20. Les jetons de continuation peuvent expirer
  24. 21. Lier les curseurs à la forme de la requête d’origine
  25. 22. Encoder l’identité des filtres et du tri dans les curseurs opaques lorsque c’est utile
  26. 23. Signer les curseurs lorsque les clients ne doivent pas pouvoir les altérer
  27. 24. Ne chiffrer les curseurs que lorsque la confidentialité est nécessaire
  28. 25. Valider la taille de page
  29. 26. Plafonner ou rejeter les demandes de pages trop grandes
  30. 27. Ne pas modifier la taille de page en silence sans prévenir le client
  31. 28. Conserver les filtres d’une page à l’autre
  32. 29. Conserver l’ordre de tri d’une page à l’autre
  33. 30. Paginer après le filtrage, pas avant
  34. 31. Paginer sur un grain métier stable
  35. 32. Éviter de paginer une requête non déterministe
  36. 33. Ne jamais se fier à l’ordre physique des lignes dans la base de données
  37. 34. Utiliser aussi un ordre unique pour la pagination vers l’arrière
  38. 35. Exemple de réponse avec curseur vers l’avant
  39. 36. Exemple de pageInfo compatible avec le parcours vers l’arrière
  40. 37. Pagination par liens
  41. 38. Pagination par en-tête HTTP Link
  42. 39. Boucle client pour la pagination par curseur
  43. 40. Ne pas s’arrêter uniquement en fonction de la longueur de la page
  44. 41. Boucle client avec offset
  45. 42. Réessayer une page sans faire avancer l’état
  46. 43. Rendre le traitement des pages idempotent lorsque c’est possible
  47. 44. Ne pas supposer une livraison exactly-once grâce à la pagination
  48. 45. N’enregistrer le checkpoint du jeton de continuation qu’après un traitement durable
  49. 46. Stocker les checkpoints de curseur avec l’identité de la requête
  50. 47. L’expiration des curseurs exige une stratégie de redémarrage
  51. 48. Utiliser des watermarks pour la synchronisation incrémentale
  52. 49. Ajouter un critère de départage à la synchronisation par watermark
  53. 50. Utiliser avec précaution des bornes incrémentales semi-ouvertes
  54. 51. Éviter updated_at > last_timestamp sans gestion des égalités
  55. 52. La pagination par offset peut ralentir avec des offsets profonds
  56. 53. La pagination keyset fonctionne mieux avec des index adaptés
  57. 54. Éviter les grosses jointures après la pagination si elles changent la multiplicité des lignes
  58. 55. Éviter la pagination après une multiplication des lignes
  59. 56. Renvoyer une dernière page vide de façon cohérente
  60. 57. Un curseur invalide doit être une erreur client
  61. 58. Ne pas exposer de traces de pile lorsque le décodage du curseur échoue
  62. 59. Les limites de débit s’appliquent à l’ensemble de la pagination
  63. 60. Les chaînes de curseurs séquentielles sont souvent séquentielles par nature
  64. 61. Paralléliser par partition, pas en devinant des curseurs
  65. 62. La taille de page influe sur le débit et sur le coût d’un échec
  66. 63. Compresser les réponses paginées volumineuses
  67. 64. Limiter les champs lorsque c’est pris en charge
  68. 65. Éviter de renvoyer d’énormes collections imbriquées dans chaque élément paginé
  69. 66. La pagination et le tri doivent être compatibles
  70. 67. Rejeter les champs de tri non pris en charge
  71. 68. Valider les entrées numériques de pagination
  72. 69. Éviter le dépassement d’entier dans le calcul de l’offset
  73. 70. Utiliser un ordre par défaut stable
  74. 71. Tenir compte du comportement en cas de suppression
  75. 72. Tenir compte des mises à jour des clés de tri
  76. 73. Préférer des clés monotones immuables pour les flux de type stream
  77. 74. Les UUID sont uniques, mais pas forcément utiles comme clés de tri
  78. 75. La pagination ne remplace pas un export en masse
  79. 76. Utiliser 202 pour la création d’un export asynchrone
  80. 77. Documenter la cohérence des pages
  81. 78. Documenter le cycle de vie des curseurs
  82. 79. Superviser le comportement de la pagination
  83. 80. Détecter les usages pathologiques de l’offset
  84. Interpréter le résultat
  85. Points à vérifier
  86. Enregistrements dupliqués d’une page à l’autre
  87. Enregistrements manquants
  88. Les pages profondes ralentissent
  89. Un curseur devient soudainement invalide
  90. Le client boucle indéfiniment
  91. Le client s’arrête trop tôt
  92. Notes de production
  93. La sémantique de pagination fait partie du contrat de l’API
  94. Un ordre déterministe est obligatoire
  95. Les valeurs de curseur doivent généralement être opaques
  96. La pagination ne garantit pas la cohérence d’instantané
  97. Les nouvelles tentatives et les checkpoints comptent
  98. L’extraction en masse peut nécessiter une autre API
  99. Erreurs fréquentes
  100. 1. Paginer sans ORDER BY
  101. 2. Trier uniquement par un horodatage non unique
  102. 3. Utiliser par défaut la pagination par offset pour d’énormes jeux de données modifiables
  103. 4. Supposer que la pagination par curseur crée un instantané
  104. 5. Laisser les clients choisir une taille de page illimitée
  105. 6. Faire avancer le curseur avant que le traitement de la page soit durable
  106. 7. Supposer que des pages courtes signifient la fin des données
  107. 8. Réutiliser un curseur avec des filtres ou un tri différents
  108. 9. Renvoyer des totaux exacts lorsqu’ils sont trop coûteux
  109. 10. Utiliser la pagination pour des exports de données massifs
  110. Étape suivante
  111. Pour aller plus loin

Problème

Un endpoint d’API peut renvoyer trop de données pour une seule réponse.

La pagination résout le problème de transport, mais des incidents de production apparaissent lorsque les ingénieurs ne définissent pas :

  • l’ordre de tri
  • les limites des pages
  • le comportement lorsque les données changent
  • la sémantique de continuation
  • la taille de page maximale
  • le comportement des nouvelles tentatives
  • la gestion des lignes dupliquées et manquantes
  • la façon dont les clients savent qu’ils ont terminé

L’objectif est de choisir un modèle de pagination adapté aux données et de rendre le parcours prévisible, aussi bien pour les producteurs que pour les consommateurs de l’API.

Réponse rapide

Utilisez ce modèle de décision :

API d’administration petite/simple
→ le numéro de page ou l’offset peut suffire

Grand jeu de données ordonné
→ pagination par curseur ou keyset

Jeu de données qui change rapidement
→ curseur/keyset avec un ordre déterministe

Le backend/fournisseur renvoie déjà des jetons de continuation
→ exposer ou encapsuler la sémantique des jetons de continuation

Besoin d’un accès direct à la « page 57 »
→ pagination par page/offset

Besoin d’un parcours séquentiel efficace
→ pagination par curseur/keyset

Exemple simple avec offset :

GET /v1/orders?limit=100&offset=200

Exemple avec curseur :

GET /v1/orders?limit=100&after=eyJpZCI6MTIzNDU2fQ

Exemple avec keyset :

GET /v1/orders?limit=100&after_created_at=2026-10-04T14:00:00Z&after_id=123456

La règle la plus importante est :

la pagination exige un ordre déterministe

Code / commandes

1. Pagination avec limite seule

Exemple :

GET /v1/orders?limit=100

Ce contrat est incomplet si l’API ne définit pas aussi :

  • l’ordre de tri
  • le mécanisme de continuation
  • la limite maximale

Une limite seule ne constitue pas un contrat de pagination complet.


2. Pagination par offset

GET /v1/orders?limit=100&offset=200

Forme SQL équivalente :

SELECT
    order_id,
    created_at,
    amount
FROM dbo.orders
ORDER BY created_at, order_id
OFFSET 200 ROWS
FETCH NEXT 100 ROWS ONLY;

À utiliser lorsque :

  • le volume de données est modéré
  • l’accès direct à une page donnée compte
  • la modification du jeu de données pendant le parcours n’est pas une préoccupation majeure

3. Pagination par numéro de page

GET /v1/orders?page=3&pageSize=100

Le serveur effectue généralement la conversion :

offset = (page - 1) * pageSize

Ce modèle est facile à comprendre pour les clients.

Il présente les mêmes limites fondamentales de cohérence et de performance que la pagination par offset.


4. Renvoyer des métadonnées de pagination

Exemple de réponse :

{
  "items": [
    {
      "orderId": 123
    }
  ],
  "page": 3,
  "pageSize": 100,
  "hasNext": true
}

Ne renvoyez totalCount que si vous pouvez le calculer à un coût acceptable et que sa sémantique est claire.


5. Prudence avec les totaux

Ce modèle :

{
  "totalCount": 98765432
}

peut nécessiter un comptage coûteux sur l’ensemble du jeu de données filtré.

Ne promettez pas un total exact si le produire rend chaque requête coûteuse.

Alternatives :

hasNext
nextCursor
approximateCount
total renvoyé par un endpoint distinct

si elles conviennent au produit.


6. Pagination par curseur

Requête :

GET /v1/orders?limit=100&after=opaque-cursor-value

Réponse :

{
  "items": [
    {
      "orderId": 123
    }
  ],
  "nextCursor": "opaque-cursor-value-2",
  "hasNext": true
}

À utiliser lorsque les clients avancent principalement de façon séquentielle.


7. Rendre les curseurs opaques pour les clients

Préférez :

after=eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTA0VDE0OjAwOjAwWiIsImlkIjoxMjM0NTZ9

plutôt que d’obliger le client à comprendre les clés de stockage internes.

Un curseur opaque laisse au serveur la liberté de changer d’implémentation plus tard.


8. Le contenu d’un curseur peut encoder l’état du tri

Conceptuellement, un curseur peut représenter :

{
  "createdAt": "2026-10-04T14:00:00Z",
  "orderId": 123456
}

Le client doit le traiter comme opaque.

Le serveur peut l’encoder ou le signer selon les besoins.


9. Pagination keyset

Requête :

GET /v1/orders?limit=100&afterCreatedAt=2026-10-04T14:00:00Z&afterId=123456

Condition de style SQL :

WHERE
    created_at > @after_created_at
    OR (
        created_at = @after_created_at
        AND order_id > @after_id
    )
ORDER BY
    created_at,
    order_id

Cela évite de parcourir puis d’ignorer un offset important.


10. Utiliser un critère de départage déterministe

Mauvais :

ORDER BY created_at

si de nombreuses lignes partagent le même horodatage.

Mieux :

ORDER BY
    created_at,
    order_id

La dernière colonne de tri doit rendre l’ordre des lignes déterministe.


11. Aligner le prédicat keyset sur le sens du tri

Ordre croissant :

WHERE
    created_at > @last_created_at
    OR (
        created_at = @last_created_at
        AND order_id > @last_order_id
    )
ORDER BY
    created_at ASC,
    order_id ASC

Ordre décroissant :

WHERE
    created_at < @last_created_at
    OR (
        created_at = @last_created_at
        AND order_id < @last_order_id
    )
ORDER BY
    created_at DESC,
    order_id DESC

Les opérateurs de comparaison doivent correspondre au sens de tri demandé.


12. Pagination keyset composite

Si l’ordre est :

tenant_id
created_at
order_id

le prédicat de continuation doit préserver le même ordre lexicographique.

Ne paginez pas en n’utilisant qu’une partie de la clé de tri.


13. Ne pas exposer les offsets de lignes de la base de données comme curseur métier stable

Un offset identifie une position dans un ordre de résultats donné, à un instant donné.

Ce n’est pas un identifiant stable.

Si des lignes sont insérées ou supprimées, les offsets suivants peuvent se décaler.


14. La pagination par offset peut sauter des lignes lors d’insertions concurrentes

Exemple :

Page 1 :
lignes 1–100

nouvelle ligne insérée près du début

Page 2 :
OFFSET 100

Le client peut voir :

  • une ligne dupliquée
  • une ligne sautée

selon la façon dont l’ordre s’est décalé.


15. La pagination par offset peut dupliquer des lignes lors de suppressions

Si des lignes antérieures disparaissent entre deux requêtes, les offsets se décalent vers l’arrière.

La requête suivante peut alors chevaucher des lignes déjà renvoyées.

C’est un comportement attendu pour les jeux de données modifiables.


16. La pagination keyset est généralement plus stable pour un parcours vers l’avant

Si le curseur représente la dernière clé ordonnée vue :

created_at + order_id

les nouvelles lignes insérées avant cette clé ne décalent normalement pas le point de continuation.

C’est ce qui rend la pagination par curseur/keyset intéressante pour les jeux de données modifiables.


17. La pagination par curseur ne crée pas automatiquement un instantané

Même avec des curseurs, les données sous-jacentes peuvent changer entre deux requêtes.

Si une sémantique d’instantané (snapshot) stricte est requise, il faut une conception explicite, par exemple :

  • un identifiant d’instantané/de version
  • une borne supérieure fixe
  • une sémantique d’instantané/de transaction de la base de données
  • un jeu de résultats exporté

Ne promettez pas une cohérence d’instantané si le backend ne la fournit pas réellement.


18. Ajouter une borne supérieure stable pour les parcours longs

Exemple de première requête :

GET /v1/events?limit=100

Le serveur peut établir :

snapshotMaxId = 9000000

La suite du parcours peut imposer :

event_id <= 9000000

Cela empêche les nouveaux événements d’étendre indéfiniment le jeu de données pendant un même parcours.

N’utilisez cette approche que si elle correspond à la sémantique du produit.


19. Pagination par jeton de continuation

Certains services renvoient un jeton opaque généré par le fournisseur :

{
  "items": [...],
  "continuationToken": "abc123"
}

Requête suivante :

GET /v1/items?continuationToken=abc123

Traitez le jeton comme opaque.

Ne l’analysez pas et ne le modifiez pas, sauf si le fournisseur documente explicitement sa structure.


20. Les jetons de continuation peuvent expirer

Documentez si un jeton est :

  • de courte durée
  • réutilisable
  • à usage unique
  • lié aux filtres
  • lié à l’identité de l’appelant

Les clients ne doivent pas supposer qu’un jeton de continuation fonctionne indéfiniment.


21. Lier les curseurs à la forme de la requête d’origine

Si un curseur a été généré pour :

status=active
sort=created_at

ne laissez pas le client le réutiliser avec :

status=closed
sort=name

Le serveur doit rejeter ou ignorer les combinaisons curseur/requête incompatibles.


22. Encoder l’identité des filtres et du tri dans les curseurs opaques lorsque c’est utile

Conceptuellement :

{
  "sort": "created_at,id",
  "filtersHash": "abc123",
  "lastCreatedAt": "...",
  "lastId": 123
}

Cela peut empêcher l’utilisation abusive d’un curseur avec une requête différente.

N’exposez pas inutilement des valeurs de filtre sensibles.


23. Signer les curseurs lorsque les clients ne doivent pas pouvoir les altérer

Un curseur contrôlé par le serveur peut se composer de :

données utiles
+
signature d’intégrité

afin que tout contenu de curseur modifié soit rejeté.

Ne comptez pas sur l’encodage Base64 comme protection contre l’altération.

Encoder n’est pas signer.


24. Ne chiffrer les curseurs que lorsque la confidentialité est nécessaire

Si le contenu du curseur comprend des identifiants internes ou un état sensible qui ne doit pas être visible, le chiffrement peut être approprié.

Si la confidentialité n’est pas nécessaire, un encodage opaque signé peut suffire.

Utilisez des bibliothèques ou frameworks cryptographiques éprouvés.


25. Valider la taille de page

Exemple de politique :

default = 100
max = 1000

Ne supposez pas que ces valeurs sont universellement correctes.

Choisissez-les en fonction de :

  • la largeur des lignes
  • le coût côté backend
  • la latence
  • le comportement des clients
  • les limites de débit

26. Plafonner ou rejeter les demandes de pages trop grandes

Exemple :

GET /v1/orders?limit=1000000

L’API ne doit pas accepter aveuglément des tailles de page arbitraires.

Soit :

rejeter avec une erreur de validation

soit :

plafonner au maximum documenté

Soyez cohérent.


27. Ne pas modifier la taille de page en silence sans prévenir le client

Si le client demande :

limit=1000

et que le serveur plafonne à :

500

rendez la taille de page réelle visible dans :

  • les métadonnées de la réponse
  • la documentation
  • les en-têtes

afin que le client puisse raisonner correctement.


28. Conserver les filtres d’une page à l’autre

Le code client doit envoyer le même ensemble de filtres pour chaque page.

Mauvais :

Page 1 :
status=active

Page 2 :
status omis

Cela modifie le jeu de résultats en cours de parcours.


29. Conserver l’ordre de tri d’une page à l’autre

Un curseur généré avec :

sort=created_at

ne doit pas être réutilisé avec :

sort=name

L’ordre de tri fait partie de l’état de pagination.


30. Paginer après le filtrage, pas avant

Ordre conceptuel correct :

filtrer
→ trier
→ paginer

Et non :

paginer
→ filtrer

Sinon, les tailles de page et la sémantique du parcours deviennent fausses.


31. Paginer sur un grain métier stable

Si une jointure produit plusieurs lignes par commande alors que l’API promet une commande par élément, dédoublonnez ou agrégez au grain de commande voulu avant la pagination.

Ne paginez pas sur un grain intermédiaire accidentel.


32. Éviter de paginer une requête non déterministe

Mauvais SQL :

SELECT *
FROM dbo.orders
OFFSET 0 ROWS
FETCH NEXT 100 ROWS ONLY;

sans ORDER BY.

La pagination exige un ordre stable.


33. Ne jamais se fier à l’ordre physique des lignes dans la base de données

Une table de base de données n’a aucun ordre naturel garanti, sauf si la requête en spécifie un.

Définissez toujours ORDER BY.


34. Utiliser aussi un ordre unique pour la pagination vers l’arrière

Si vous prenez en charge :

before=<cursor>

le serveur doit inverser correctement le prédicat de continuation tout en renvoyant les éléments dans l’ordre d’affichage documenté.

La pagination vers l’arrière est plus complexe que le simple remplacement de > par <.


35. Exemple de réponse avec curseur vers l’avant

{
  "items": [
    {
      "orderId": 123,
      "createdAt": "2026-10-04T14:00:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "opaque-token"
  }
}

Gardez des noms de métadonnées cohérents d’un endpoint à l’autre.


36. Exemple de pageInfo compatible avec le parcours vers l’arrière

{
  "items": [...],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": true,
    "nextCursor": "next-token",
    "previousCursor": "previous-token"
  }
}

N’exposez le parcours vers l’arrière que si l’implémentation le prend correctement en charge.


37. Pagination par liens

Une API peut renvoyer directement des URL :

{
  "items": [...],
  "links": {
    "next": "https://api.example.com/v1/orders?cursor=abc",
    "prev": null
  }
}

Cela réduit la logique de construction d’URL nécessaire côté client.


Exemple :

Link: <https://api.example.com/v1/orders?cursor=abc>; rel="next"

C’est valide et utile dans certaines API.

N’obligez pas les clients à analyser à la fois la pagination dans le corps et les en-têtes Link, sauf raison claire.


39. Boucle client pour la pagination par curseur

Exemple Python :

import requests

url = "https://api.example.com/v1/orders"
cursor = None

while True:
    params = {
        "limit": 100
    }

    if cursor:
        params["after"] = cursor

    response = requests.get(
        url,
        params=params,
        timeout=30,
    )
    response.raise_for_status()

    payload = response.json()

    for item in payload["items"]:
        process(item)

    cursor = payload.get("nextCursor")

    if not cursor:
        break

En production, ajoutez selon les besoins les nouvelles tentatives, l’authentification, la journalisation et un traitement idempotent.


40. Ne pas s’arrêter uniquement en fonction de la longueur de la page

Mauvaise logique client :

if len(items) < page_size:
    break

Cela peut échouer si l’API :

  • filtre en interne
  • plafonne les résultats de façon dynamique
  • renvoie des pages clairsemées
  • utilise une continuation côté fournisseur

Préférez des indicateurs explicites :

nextCursor
hasNext
nextLink

issus du contrat de l’API.


41. Boucle client avec offset

import requests

offset = 0
limit = 100

while True:
    response = requests.get(
        "https://api.example.com/v1/orders",
        params={
            "offset": offset,
            "limit": limit,
        },
        timeout=30,
    )
    response.raise_for_status()

    payload = response.json()
    items = payload["items"]

    for item in items:
        process(item)

    if not payload.get("hasNext"):
        break

    offset += limit

À n’utiliser que si l’API garantit ce modèle de pagination.


42. Réessayer une page sans faire avancer l’état

Comportement client correct :

demander la page
→ échec
→ réessayer la même page/le même curseur
→ succès
→ traiter en toute sécurité
→ faire avancer le curseur

Ne faites pas avancer le jeton de continuation avant que la page ait été traitée avec succès.


43. Rendre le traitement des pages idempotent lorsque c’est possible

Si le client plante après avoir traité la moitié d’une page puis réessaie cette page, des enregistrements peuvent être vus une seconde fois.

Concevez le traitement de façon à ce qu’une livraison en double ne corrompe pas l’état en aval.

Exemples :

  • upsert par clé métier
  • checkpoint après un traitement durable
  • dédoublonnage par identifiant d’événement

44. Ne pas supposer une livraison exactly-once grâce à la pagination

La pagination est un mécanisme de récupération des données.

Elle ne garantit pas qu’un client observera chaque enregistrement modifiable exactement une fois en cas de plantages, de nouvelles tentatives ou de modifications concurrentes.

Si un comportement métier proche de l’exactly-once compte, ajoutez un état durable et de l’idempotence.


45. N’enregistrer le checkpoint du jeton de continuation qu’après un traitement durable

Mauvais :

enregistrer nextCursor
→ traiter la page
→ plantage

La page peut être sautée après le redémarrage.

Plus sûr :

récupérer la page
→ traiter la page de façon durable
→ enregistrer nextCursor/le checkpoint

46. Stocker les checkpoints de curseur avec l’identité de la requête

Checkpoint :

{
  "endpoint": "/v1/orders",
  "filters": {
    "status": "active"
  },
  "cursor": "opaque-token"
}

Ne réutilisez pas un curseur stocké pour une forme de requête différente.


47. L’expiration des curseurs exige une stratégie de redémarrage

Si les curseurs peuvent expirer, les clients doivent savoir s’il faut :

  • recommencer le parcours
  • repartir de la dernière clé métier traitée
  • demander un nouvel export
  • utiliser plutôt un watermark durable

Documentez ce comportement.


48. Utiliser des watermarks pour la synchronisation incrémentale

Exemple :

updated_at > last_successful_watermark

La pagination et le chargement incrémental résolvent des problèmes différents.

Une synchronisation robuste combine souvent :

filtre incrémental
+
pagination déterministe

49. Ajouter un critère de départage à la synchronisation par watermark

Mauvais :

updated_at > 2026-10-04T14:00:00Z

si de nombreuses lignes partagent cet horodatage.

Meilleur état de continuation :

updated_at
+
id

avec une sémantique keyset.


50. Utiliser avec précaution des bornes incrémentales semi-ouvertes

Un modèle courant est :

début inclus
fin exclue

Exemple :

updated_at >= start
AND updated_at < end

Cela peut simplifier les limites entre lots adjacents.

Pour une synchronisation incrémentale paginée, définissez tout de même un ordre déterministe des lignes à l’intérieur de la fenêtre.


51. Éviter updated_at > last_timestamp sans gestion des égalités

Si plusieurs enregistrements ont :

updated_at = last_timestamp

certains peuvent être sautés après un redémarrage.

Stockez suffisamment d’état pour distinguer les lignes qui partagent le même horodatage.


52. La pagination par offset peut ralentir avec des offsets profonds

Conceptuellement :

OFFSET 10
→ plutôt peu coûteux

OFFSET 10,000,000
→ la base de données peut encore devoir localiser/parcourir/trier un grand nombre de lignes à ignorer

Le comportement exact dépend de la base de données, des index et du plan de requête.

Ne supposez pas un accès aux pages en temps constant.


53. La pagination keyset fonctionne mieux avec des index adaptés

Pour :

ORDER BY created_at, order_id

un index utile commence souvent par des colonnes de tri/filtre compatibles.

La conception des index dépend :

  • des filtres
  • de la sélectivité
  • des colonnes incluses
  • du moteur de base de données

N’ajoutez pas un index à l’aveugle uniquement parce que la pagination existe.


54. Éviter les grosses jointures après la pagination si elles changent la multiplicité des lignes

Flux conceptuel problématique :

paginer les commandes
→ joindre order_lines
→ le résultat contient désormais plusieurs lignes par commande

Si le contrat de l’API prévoit une commande par élément, enrichissez avec précaution ou agrégez les lignes de commande séparément.


55. Éviter la pagination après une multiplication des lignes

Si une jointure crée accidentellement des doublons avant la pagination, les limites des pages deviennent instables et les comptages trompeurs.

Validez le grain avant de paginer.


56. Renvoyer une dernière page vide de façon cohérente

Si un curseur demande explicitement des données au-delà de la fin, choisissez un comportement documenté, par exemple :

{
  "items": [],
  "nextCursor": null,
  "hasNext": false
}

N’alternez pas au hasard entre un 200 vide et un 404.


57. Un curseur invalide doit être une erreur client

Si un curseur est mal formé, altéré, expiré ou incompatible avec la requête, renvoyez une erreur claire destinée au client.

Exemple :

HTTP/1.1 400 Bad Request
{
  "error": "invalid_cursor",
  "message": "The pagination cursor is invalid or expired."
}

Le modèle exact de statut et d’erreur doit être cohérent avec le reste de l’API.


58. Ne pas exposer de traces de pile lorsque le décodage du curseur échoue

Les curseurs mal formés sont des entrées client, pas une excuse pour divulguer des détails internes d’analyse ou de cryptographie.

Renvoyez une erreur métier stable.


59. Les limites de débit s’appliquent à l’ensemble de la pagination

Les clients peuvent récupérer des centaines de pages.

Respectez :

  • 429
  • Retry-After
  • les quotas par client
  • les limites de concurrence

Ne parallélisez pas automatiquement toutes les requêtes de pages.


60. Les chaînes de curseurs séquentielles sont souvent séquentielles par nature

Si la page N+1 a besoin du curseur de la page N :

page 1
→ curseur 2
→ page 2
→ curseur 3

vous ne pouvez pas demander toutes les pages en parallèle en toute sécurité, sauf si l’API expose des partitions/plages indépendantes.


61. Paralléliser par partition, pas en devinant des curseurs

Si l’API prend en charge un partitionnement tel que :

tenant
plage de dates
shard
clé de partition

les clients peuvent traiter des partitions indépendantes en parallèle.

Ne fabriquez pas de valeurs de curseur futures.


62. La taille de page influe sur le débit et sur le coût d’un échec

Pages plus grandes :

moins de requêtes HTTP
payloads plus volumineux
plus de travail à refaire si une page échoue
plus de mémoire par réponse

Pages plus petites :

plus de requêtes
plus de surcoût par requête
unité de nouvelle tentative plus petite

Choisissez en fonction des caractéristiques réelles de la charge de travail.


63. Compresser les réponses paginées volumineuses

Si c’est pris en charge, les clients peuvent envoyer :

Accept-Encoding: gzip

ou utiliser :

curl --compressed ...

Cela peut réduire le volume transféré pour du JSON riche en texte.


64. Limiter les champs lorsque c’est pris en charge

Exemple :

GET /v1/orders?fields=orderId,createdAt,amount&limit=100

Réduire la largeur des lignes peut améliorer le débit de la pagination.

N’exposez la projection de champs que si le contrat de votre API la prend en charge en toute sécurité.


65. Éviter de renvoyer d’énormes collections imbriquées dans chaque élément paginé

Exemple :

100 commandes
×
des milliers de lignes de commande imbriquées

peut annuler l’intérêt de la pagination.

Envisagez :

  • des endpoints enfants distincts
  • des résumés
  • des expansions bornées
  • des paramètres d’inclusion explicites

66. La pagination et le tri doivent être compatibles

Si les clients peuvent trier par des colonnes arbitraires :

?sort=name

le serveur a besoin d’un critère de départage déterministe pour chaque tri pris en charge.

Exemple :

sort=name
ordre effectif :
name, id

67. Rejeter les champs de tri non pris en charge

N’interpolez pas directement dans le SQL des expressions de tri arbitraires fournies par le client.

Établissez une liste blanche des champs et des sens de tri pris en charge.

C’est à la fois une question d’exactitude et de sécurité.


68. Valider les entrées numériques de pagination

Exemples de requêtes invalides :

limit=-1
offset=-50
page=0
pageSize=999999999

Renvoyez une erreur de validation maîtrisée.

Ne laissez pas des valeurs invalides atteindre le code de stockage sans contrôle.


69. Éviter le dépassement d’entier dans le calcul de l’offset

Pour les API par numéro de page :

offset = (page - 1) * pageSize

validez les bornes avant de calculer ou d’exécuter des valeurs très grandes.

C’est particulièrement important dans les langages serveur fortement typés et les grandes API publiques.


70. Utiliser un ordre par défaut stable

Si le client ne précise pas l’ordre de tri, documentez celui que le serveur applique par défaut.

Exemple :

created_at DESC, id DESC

Ne changez pas l’ordre par défaut en silence d’une version à l’autre.


71. Tenir compte du comportement en cas de suppression

Avec la pagination keyset :

dernière clé vue
→ continuer après cette clé

la suppression d’une ligne antérieure ne décale normalement pas le curseur.

Avec la pagination par offset, une suppression peut décaler les positions suivantes.

C’est l’une des raisons pour lesquelles la pagination keyset est souvent plus stable pour les données modifiables.


72. Tenir compte des mises à jour des clés de tri

Si la colonne de tri d’une ligne change pendant que le client parcourt les données, la ligne peut se déplacer :

avant le curseur
ou
après le curseur

et être manquée ou observée deux fois.

Si cela compte, utilisez :

  • une clé de tri immuable
  • une borne d’instantané
  • une séquence en ajout seul (append-only)
  • une conception dédiée de synchronisation/flux de changements

73. Préférer des clés monotones immuables pour les flux de type stream

Exemples :

event_id
sequence_number
commit_position

lorsqu’elles sont disponibles.

Elles simplifient le parcours keyset et les checkpoints.

N’inventez pas une sémantique monotone pour des identifiants qui ne sont pas réellement ordonnés.


74. Les UUID sont uniques, mais pas forcément utiles comme clés de tri

Un UUID aléatoire peut être un excellent identifiant unique, mais une mauvaise clé de pagination chronologique.

Utilisez-le comme critère de départage si nécessaire, pas comme substitut à un ordre porteur de sens, sauf si sa sémantique d’ordre est délibérée.


75. La pagination ne remplace pas un export en masse

Si un client a besoin de :

centaines de millions de lignes

envisagez :

  • un job d’export asynchrone
  • une livraison de fichiers
  • un stockage objet
  • un mécanisme de partage de données

plutôt que d’imposer des millions d’appels de pages à l’API.


76. Utiliser 202 pour la création d’un export asynchrone

Exemple :

POST /v1/exports

Réponse :

HTTP/1.1 202 Accepted
Location: /v1/exports/job-123

Le client peut ensuite interroger périodiquement l’état ou recevoir une notification lorsque l’export est prêt.


77. Documenter la cohérence des pages

Indiquez aux clients si la pagination est :

au mieux sur des données en direct
cohérente avec un instantané
bornée par le watermark de la première requête
à cohérence éventuelle

Ne laissez pas le comportement face aux modifications indéfini pour les intégrations critiques.


78. Documenter le cycle de vie des curseurs

Précisez :

opaque ?
expiration ?
réutilisable ?
lié aux filtres ?
lié à l’appelant ?
vers l’avant uniquement ?

Cela évite que les clients s’appuient sur des hypothèses dangereuses.


79. Superviser le comportement de la pagination

Métriques utiles :

requêtes par endpoint
taille de page
offset le plus profond
pages par parcours
erreurs de curseur
taux de 429
octets de réponse
latence par taille de page

Elles peuvent révéler des clients qui abusent des grands offsets ou qui récupèrent des jeux de données entiers de façon inefficace.


80. Détecter les usages pathologiques de l’offset

Exemple :

offset=50,000,000

peut indiquer que le client utilise un endpoint de liste comme mécanisme d’export en masse.

Envisagez plutôt un curseur ou une API d’export.

Interpréter le résultat

Modèle Point fort Point faible
Numéro de page Simple pour les humains/l’interface Mêmes problèmes d’offset profond et de modifications que l’offset
Offset + limite Simple, permet l’accès direct Peut devenir lent et instable sur des jeux de données changeants
Curseur Abstraction d’API stable Généralement séquentiel ; le cycle de vie du jeton doit être défini
Keyset Parcours vers l’avant efficace et stable Accès direct plus difficile ; exige une clé déterministe
Jeton de continuation Fonctionne bien avec la pagination native du fournisseur/backend Souvent opaque/propre au fournisseur
Instantané + curseur Forte cohérence du parcours Plus de complexité/d’état côté backend
Export asynchrone Idéal pour les très gros volumes à récupérer Pas de navigation interactive par page

Le choix de conception central est :

accès direct aux pages
ou
parcours stable et efficace

Points à vérifier

Enregistrements dupliqués d’une page à l’autre

Vérifiez :

  • la pagination par offset sur des données changeantes
  • un ordre de tri non unique
  • les mises à jour des clés de tri
  • le comportement des nouvelles tentatives

Enregistrements manquants

Vérifiez :

  • le prédicat du curseur
  • les égalités d’horodatage
  • un ordre instable
  • le moment du checkpoint
  • les changements de filtres entre les requêtes

Les pages profondes ralentissent

La pagination par offset parcourt ou ignore peut-être des préfixes de plus en plus longs.

Examinez les plans de requête et envisagez la pagination keyset.

Un curseur devient soudainement invalide

Vérifiez :

  • l’expiration
  • les changements de filtres/de tri
  • les clés de signature des jetons
  • les règles de continuation du backend/fournisseur

Le client boucle indéfiniment

Vérifiez :

  • un même curseur répété
  • la logique de hasNext
  • un serveur qui renvoie des jetons de continuation qui ne progressent pas
  • un client qui n’enregistre pas le nouveau curseur dans son checkpoint

Le client s’arrête trop tôt

Vérifiez s’il suppose à tort que :

items.length < taille de page demandée

signifie la fin.

Préférez des métadonnées de continuation explicites.

Notes de production

La sémantique de pagination fait partie du contrat de l’API

Modifier :

le tri par défaut
la structure du curseur
le plafond de taille de page
le comportement de continuation

peut casser les clients.

Traitez ces éléments comme un comportement versionné.

Un ordre déterministe est obligatoire

Chaque résultat paginé a besoin d’un ordre complet.

Si la colonne de tri visible n’est pas unique, ajoutez un critère de départage.

Les valeurs de curseur doivent généralement être opaques

Cela réduit le couplage des clients aux clés de stockage internes et permet à l’implémentation d’évoluer.

La pagination ne garantit pas la cohérence d’instantané

Si une cohérence stricte compte, implémentez-la explicitement.

Les nouvelles tentatives et les checkpoints comptent

Un client robuste doit pouvoir réessayer une page sans :

  • sauter de données
  • corrompre l’état en aval

L’extraction en masse peut nécessiter une autre API

La pagination est idéale pour un parcours interactif borné, pas toujours pour un export à l’échelle d’un entrepôt de données.

Erreurs fréquentes

1. Paginer sans ORDER BY

L’ordre des lignes dans la base de données n’est pas garanti.

2. Trier uniquement par un horodatage non unique

Les lignes avec des horodatages égaux peuvent passer d’un côté à l’autre des limites de page.

3. Utiliser par défaut la pagination par offset pour d’énormes jeux de données modifiables

Les offsets profonds et le déplacement des lignes deviennent problématiques.

4. Supposer que la pagination par curseur crée un instantané

Ce n’est pas le cas, sauf si elle a été explicitement conçue ainsi.

5. Laisser les clients choisir une taille de page illimitée

Une seule requête peut se transformer en export en masse.

6. Faire avancer le curseur avant que le traitement de la page soit durable

Un plantage peut faire sauter des enregistrements.

7. Supposer que des pages courtes signifient la fin des données

Utilisez des métadonnées de continuation explicites.

8. Réutiliser un curseur avec des filtres ou un tri différents

Le curseur peut ne plus représenter le même jeu de résultats.

9. Renvoyer des totaux exacts lorsqu’ils sont trop coûteux

Ne faites pas payer un comptage complet à chaque requête de page, sauf si le produit en a vraiment besoin.

10. Utiliser la pagination pour des exports de données massifs

Utilisez un modèle d’export asynchrone ou de partage de données lorsque l’échelle l’exige.

Étape suivante

Choisissez le modèle en fonction de la forme des données et du besoin du client.

  • Jeu de données petit et stable avec navigation directe entre les pages → la pagination par page/offset peut suffire.
  • Grand jeu de données parcouru séquentiellement → utilisez la pagination par curseur/keyset.
  • Le jeu de données change souvent pendant que les clients le parcourent → utilisez une sémantique keyset/curseur déterministe et documentez la cohérence.
  • Les horodatages servent de clé de curseur → ajoutez un critère de départage unique.
  • Le client a besoin d’un redémarrage fiable → n’enregistrez le checkpoint qu’après un traitement durable.
  • Le curseur expire → définissez le comportement de redémarrage/de watermark.
  • Les offsets profonds sont lents → examinez le plan de requête et évoluez vers la pagination keyset.
  • Le client a besoin de toutes les données à l’échelle d’un entrepôt → concevez un export asynchrone plutôt que des millions de requêtes de pages.
  • Les résultats de pagination sont dupliqués ou manquants → examinez l’ordre de tri, les modifications, les prédicats de continuation et la logique de checkpoint.
  • La requête d’API elle-même échoue → passez à Diagnostiquer les requêtes d’API.

← Tous les aide-mémoire