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