Was ist API Pagination? Cursor vs Offset Strategien

Was ist API Pagination?

API Pagination ist die Praxis, ein großes Result-Set in kleinere Chunks ("Pages") zu splitten, die über multiple Requests returnt werden. Ohne Pagination würde ein Endpoint, der 1M Records returnt, die Datenbank crashen, Memory exhausten oder timeouten.

Die richtige Pagination-Strategie hängt von Daten-Shape, Traffic-Patterns und UX-Needs ab. Offset/Limit ist simpel aber bricht at Scale. Cursor-based ist effizient aber schwerer zu nutzen. Keyset ist das moderne Best-of-Both.

Die vier Haupt-Pagination-Strategien

Offset/Limit Pagination

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

Pros: Simpel zu implementieren; supportet Jump-to-Page UX.

Cons: Langsam bei großen Offsets; inkonsistent wenn Daten sich ändern.

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

Cursor-based Pagination

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

Pros: Stabil über Daten-Changes; schnell; ideal für Infinite-Scroll.

Cons: Kein Jump-to-Page; Cursor ist opaque.

Keyset (Seek) Pagination

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

Pros: Selbe Geschwindigkeit wie Cursor; simplere API; stabil.

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

Performance-Vergleich

Keyset ist konstante Zeit. Offset/Limit wird langsamer mit jeder Page.

Häufige API-Pagination-Patterns

Link-Header (RFC 5988)

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

Pagination-Metadata im Response-Body

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

Pagination Best Practices

• Default + Max Limit.
• Keyset over Offset für große Datasets.
• Stabile Sort.
• Sort-Key indexieren.
• Strategie dokumentieren.
• Total-Counts at Scale skippen.
• Page 1 cachen.
• Streaming erwägen.

Häufige Pagination-Fallstricke

• Langsame Deep-Pages.
• Inkonsistente Results.
• Missing Items während Pagination.
• Total-Count at Scale.
• Kein Max-Limit.
• Page-Numbers in URL forever.

FAQ: API Pagination

Sollte ich Offset oder Cursor-Pagination nutzen?

Cursor für alles mit >1000 Records oder Live-Feeds. Offset für kleine Admin-Listen.

Wie implementiere ich Cursor-Pagination?

Sort-Key des letzten Items als base64 JSON encoden.

Wie bekomme ich Total-Count mit Cursor-Pagination?

Separate COUNT(*)-Query, oder Total komplett skippen.

Was ist die maximale Page-Size?

Hängt von Payload ab. Typisch: 100-1000.

Sollten Pagination-Params im Query-String oder Body sein?

Query-String für GET; Body acceptable für POST.

Brauche ich beide next und prev Cursors?

Forward-only ist meist genug.

Wie handhabt GraphQL Pagination?

Relay-Cursor-Connections-Spec.

Load-Testen Sie paginierte APIs mit LoadFocus

Pagination-Perf-Bugs zeigen sich nur unter echtem Traffic. LoadFocus läuft JMeter- und k6-Scripts, die Deep-Pages mit realistischer Concurrency aus 25+ Regionen treffen. Registrieren bei loadfocus.com/signup.