Qu'est-ce que l'API Pagination ? Cursor vs Offset

Qu'est-ce que la pagination API ?

La pagination API est la pratique de diviser un gros result set en chunks plus petits ("pages") retournés sur plusieurs requêtes. Sans pagination, un endpoint retournant 1M records crasherait la base de données, épuiserait la mémoire ou timeouterait.

La bonne stratégie pagination dépend du shape données, patterns trafic et besoins UX.

Les quatre stratégies pagination principales

Pagination Offset/Limit

GET /api/users?offset=200&limit=50

Pros : Simple à implémenter ; supporte UX jump-to-page.

Cons : Lent à grands offsets ; inconsistant si données changent.

SELECT * FROM users ORDER BY created_at LIMIT 50 OFFSET 200;

Pagination Cursor-based

GET /api/users?cursor=eyJpZCI6MTIzNDV9&limit=50

Pros : Stable à travers changements données ; rapide ; idéal pour infinite scroll.

Cons : Pas de jump-to-page ; cursor opaque.

Pagination Keyset (seek)

GET /api/users?after_id=12345&limit=50

Pros : Même vitesse que cursor ; API plus simple ; stable.

SELECT * FROM users WHERE id > 12345 ORDER BY id LIMIT 50;

Comparaison performance

Keyset est temps constant.

Patterns pagination API courants

Link header (RFC 5988)

Link: <https://api.example.com/users?offset=50&limit=50>; rel="next"

Métadonnées pagination dans body response

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "page": 5,
    "per_page": 50
  }
}

Best practices pagination

• Default + max limit.
• Keyset over offset pour gros datasets.
• Sort stable.
• Indexer sort key.
• Documenter la stratégie.
• Skip total counts à scale.
• Cacher page 1.
• Considérer streaming.

Pièges courants pagination

• Pages profondes lentes.
• Résultats inconsistants.
• Items manquants durant pagination.
• Total count à scale.
• Pas de max limit.
• Numéros page in URL forever.

FAQ : pagination API

Devrais-je utiliser offset ou cursor pagination ?

Cursor pour tout avec >1000 records ou feeds live.

Comment implémenter cursor pagination ?

Encoder sort key du dernier item comme base64 JSON.

Comment obtenir total count avec cursor pagination ?

Query COUNT(*) séparée, ou skip total entièrement.

Quelle est la max page size que je devrais supporter ?

Dépend du payload. Typique : 100-1000.

Params pagination dans query string ou body ?

Query string pour GET ; body acceptable pour POST.

Ai-je besoin des deux cursors next et prev ?

Forward-only est généralement suffisant.

Comment GraphQL gère-t-il la pagination ?

Spec Relay Cursor Connections.

Load-testez les APIs paginées avec LoadFocus

Les bugs perf pagination ne se montrent que sous trafic réel. LoadFocus exécute des scripts JMeter et k6 qui hittent les pages profondes avec une concurrence réaliste depuis 25+ régions. Inscrivez-vous sur loadfocus.com/signup.