Naar de inhoud
maarten.
Gedetailleerd beeld van een open boek met lintbladwijzer op een houten bureau.
Alle stories

API-paginering: offset, cursor en data

Maarten Soetens 12 min lezen

API-paginering bepaalt hoe clients grote collecties stapsgewijs ophalen en hoe betrouwbaar die resultaten blijven wanneer data verandert. Je leest hoe offset- en cursorpaginering werken, welke rol sortering en database-indexen spelen en waar het ophalen van grote datasets vaak misgaat.

Offsetpaginering: eenvoudig voor clients, zwaarder bij diepe pagina’s

Offsetpaginering werkt simpel: je vraagt om bijvoorbeeld vijftig items, en je zegt tegen de API hoeveel resultaten die moet overslaan. Met ?limit=50&offset=100 krijg je dus de derde set van vijftig items, net als bij een tabel met paginanummers in een webapp. Zo'n aanpak geeft je snel zicht op het totaal en springt vlot naar een specifieke pagina. Dat helpt vooral bij zoekschermen en overzichten met filters.

Maar die eenvoud zit aan de voorkant. De achterkant merkt bij grote offsets juist zwaardere lasten. De database moet nog steeds alle overgeslagen records doorlopen om bij de juiste resultaten uit te komen. Als je offset steeds groter wordt, kan het zoeken dus flink vertragen, zeker als er geen goede index is. De echte prestaties hangen af van hoe je database je data bewaart en welke indexen zijn ingesteld. Puur gebruik van limit en offset op een groeiende tabel is technisch gezien niet zuinig.

Offsetpaginering werkt goed bij kleine sets die lang hetzelfde blijven, waar je precies wilt kunnen springen. Leg vast hoe groot een pagina maximaal mag zijn. Controleer dat offset niet negatief is, en bepaal hoe je reageert bij ongeldige input. Laat je limit-parameter niet onbeperkt hoog worden, anders krijg je ineens teveel data in één verzoek. Vergeet ook niet om altijd te sorteren: zonder sortering krijg je geen betrouwbare paginaverdeling. Voor maatwerk rond API’s en databases kun je een PHP developer inschakelen.

Cursorpaginering: verdergaan vanaf een record in de sortering

Cursorpaginering werkt met een ‘sleutel’ die de plek in een lijst aangeeft. Zo krijg je bijvoorbeeld een set van vijftig items, en een cursor waarmee je de volgende batch kunt ophalen. Die cursor verwijst vaak naar een combinatie zoals een aanmaakdatum en een unieke id. Je hoeft zelf niet te berekenen hoeveel pagina’s er zijn, je gaat gewoon verder waar je was gebleven door de cursor terug te sturen. Een vergelijkbaar patroon met page tokens staat in de officiële Google Cloud-documentatie.

Vaak kan de database vanaf het juiste punt in een index verderlezen, mits de cursor overeenkomt met de sorteervolgorde en filters van de query. Je voorkomt zo het scannen van honderden of duizenden rijen bij een diepe pagina. Maar let op: een cursor op alleen een datum werkt niet als daar meerdere items dezelfde waarde hebben. Voeg altijd een uniek kenmerk toe zodat je niets mist en geen dubbelen krijgt bij het ophalen van de volgende pagina.

Springen naar een willekeurige pagina lukt hiermee eigenlijk niet. Cursornavigatie is bedoeld voor ‘volgende’ en ‘vorige’, niet voor snel op pagina 27 belanden. Ontwerp daarom je API-response met duidelijke velden zoals een cursor voor de ‘volgende’ batch en geef aan wanneer er geen data meer is. Het totaal aantal records hoeft de server niet te berekenen; die informatie past niet goed bij het idee van cursorpaginering.

Stabiele sortering voorkomt ontbrekende en dubbele records

Alles valt of staat met een vastgelegde volgorde. Als je sorteert op een niet-uniek veld, zoals alleen datum of status, heb je kans dat records iedere keer anders uitvallen. De database mag zelf kiezen hoe die items met dezelfde waarde plaatst, dus kun je ineens een dubbel record terugzien, of juist eentje missen rond een paginawissel.

Voeg daarom altijd iets unieks toe aan je sortering. Bijvoorbeeld, eerst op created_at en daarna op id. Dan weet je precies welke volgorde records met dezelfde aanmaakdatum krijgen. Alle onderdelen van je cursor moeten terugkomen in de vervolgquery, en sorteren moet op precies dezelfde manier gebeuren als de eerste keer. ‘Descending’ of ‘ascending’ maakt dan nog uit voor je vergelijkingen in de query zelf.

Welke velden je mag gebruiken voor sorteren, en in welke combinatie, moet je API-contract vastleggen. Laat niet toe dat een client ieder willekeurig databaseveld kiest; zonder goede index kost dat kracht. Denk aan velden waar geen waarde is en aan de manier waarop null’s worden gesorteerd, want dat kan tussen verschillende databases verschillen. Schrijf dus niet alleen op dat sorteren mogelijk is, maar geef aan hoe de logica werkt en welke velden als tie-breaker dienen.

Veranderende datasets maken paginagrenzen beweeglijk

Een lijst ophalen gebeurt meestal in stukjes. Tussen twee API-verzoeken door kan een ander item zijn toegevoegd, verwijderd of aangepast. Dat veroorzaakt bij offsetpaginering een bekend probleem: als iemand een item vóór jouw huidige positie toevoegt, verschuiven alle rijnummers. Je kunt dan per ongeluk iets dubbel zien, of juist overslaan. Bij verwijderen krijg je hetzelfde effect: de offset wijst niet meer naar dezelfde data als bij de vorige query.

Cursorpaginering beperkt dat: door op een exacte plek door te gaan (en niet op een rangnummer) krijg je minder snel verschuivingen. Let wel: ook dit is geen snapshot. Als tijdens het ophalen een item van plek wisselt, kan het alsnog verschuiven tussen pagina’s. Nieuwe items vóór je cursor komen niet vanzelf terug. Kies dus wat voor jouw usecase belangrijk is, altijd recente data, of liever een vastgelegd moment in de tijd.

Wil je een momentopname, dan kun je een grens als ‘tot en met deze datum’ of een unieke snapshot-id vastleggen. Dat voorkomt dat er in de reeks nieuwe records opduiken, maar updates en deletes blijven lastig. Snapshotisolatie via een database-actie kan, maar dat geeft weer operationele nadelen bij veel losse HTTP-calls. Geef altijd duidelijk aan in je documentatie welk consistentieniveau je biedt, zodat clients weten waar ze aan toe zijn.

Databaseprestaties hangen af van indexen en queryvorm

Of je voor offset of cursor kiest, hangt direct samen met hoe je database records leest. Cursorqueries filteren meestal op de laatst opgehaalde sorteerwaarden, gevolgd door precies dezelfde sorteervolgorde en een limiet. Sluit dat allemaal aan op een index, dan kan de database vanaf een bepaalde plek verderlezen. Maar als de index mist of niet lekker past op je query, dan krijg je alsnog traagheid omdat de database meer werk moet doen.

Bedenk van tevoren hoe je samengestelde indexen eruit moeten zien. Sorteer je steeds per account op datum en id, overweeg dan een index in diezelfde volgorde. De precieze indexkeuze hangt af van je filters en het type database. Check je queryplan met echte data, waarbij je ook ‘diepe’ paginanummers en veelvoorkomende filters probeert. Wat lokaal direct lijkt te werken, kan op productie met veel data ineens zeer langzaam zijn.

Paginagrootte speelt ook. Een kleine limiet, bijvoorbeeld 20, maakt je response snel en licht, maar je doet meer netwerkcalls. Grote limieten drukken het aantal verzoeken, maar kosten flink meer geheugen en bandbreedte in één keer. Meet de tijd, gecachte pagina’s, fouten en geheugendruk. Zet altijd een maximum op limit om plotselinge grote pieken te voorkomen. Voor counts geldt nog iets anders: een nauwkeurige telling over gefilterde data kan juist zwaarder wegen dan het ophalen zelf.

Cursors ontwerpen zonder interne querydetails bloot te leggen

De cursor is een contract met de client, hoewel die zelden weet wat erin zit. Vaak bevat de waarde de sorteerkey, unieke id en zo nodig extra context. Je codeert die gegevens meestal (bijvoorbeeld Base64) zodat de server bij een volgend verzoek weer verder kan. Maar dat verstopt de inhoud niet: alles wat erin zit kan iemand met minimale moeite weer uitpakken, en het is niet gegarandeerd integer als je geen validatie of handtekening gebruikt.

Kan een aanpassing van de cursor zomaar een query beïnvloeden? Dan kun je beter een ondertekend token gebruiken, of een verwijzing naar een sessiestatus op de server. Controleer altijd de structuur en gebruikte typen en breng de relevante context in, zoals filters en sortering. Een cursor gekoppeld aan een filter op organisatie mag niet ineens voor een andere organisatie werken.

Verlopen, ongeldige of gemanipuleerde cursors horen direct als fout te worden teruggegeven, liefst herkenbaar aan een eigen foutcode. Ga niet alsnog gokken of proberen iets te herstellen; dat leidt tot onvoorspelbare resultaten. Houd je cursorformaat uitbreidbaar (denk aan een versieveld) zodat latere wijzigingen niet alles breken. Neem geen privacygevoelige info op, zelfs niet versleuteld. Een cursor komt tenslotte zomaar in logs terecht, of slingert rond in monitoring of browsergeschiedenis.

Grote datasets ophalen zonder één omvangrijk verzoek

Een hele grote lijst in één keer opvragen is technisch mogelijk, maar je loopt snel tegen time-outs aan, forse geheugendruk en afgebroken verbindingen. Kleine, gepagineerde stukken zijn handzaam, maar maken van een reeks pagina’s nog geen veilige exporttool. De client moet cursors of offsets bewaren, responses direct verwerken en kunnen doorgaan als het netwerk even hapert. Zorg dat de server per pagina werkt, niet alles in een klap eerst in het geheugen laadt.

Idempotent bulkwerk is veiliger. Sla pas de laatst verwerkte sleutel of cursor op nadat je de batch écht hebt verwerkt. Een retry van dezelfde pagina mag geen dubbele acties veroorzaken. Komen er acties voort uit de batch, zoals verwerking door een externe dienst, let dan op duplicates; een deduplicatielijst of unieke sleutel kan nodig zijn. Check of je uit de API-response (bijvoorbeeld via metadata) zeker weet dat je het einde van de scan hebt bereikt, of dat je op een andere signalering moet vertrouwen. Bij terugkerende gegevensstromen kun je workflows automatiseren.

Als je echt een hele grote collectie als bulk wilt exporteren, is een asynchrone export handiger. Dat betekent: apart aanmaken, laten draaien en later het bestand ophalen. Dan heb je meteen controle over consistentie, overdracht en fouten. Paginering is vooral geschikt als je records per stuk of paginawijs wilt verwerken. Gaat het om een compleet archief of een periodieke backup, bouw dan een aparte, robuuste exportfunctie. Een concreet voorbeeld van zo’n gegevensstroom is voorraad tussen systemen synchroniseren.

Veelvoorkomende fouten bij paginering in API-clients

Wanneer de client alleen pagina 1 inleest, krijg je geen foutmelding. De gegevens lijken compleet, maar je mist alles na het eerste deel. Zorg dus dat je altijd het navigatieveld gebruikt dat de API teruggeeft (cursor, link, indicator) en niet zomaar stopt als je een keer een korte pagina ziet. Verschillende API’s bieden daarin eigen afspraken; bouw je client rondom het gekozen model. De opmaak van links in HTTP-headers is vastgelegd in de RFC over Web Linking.

Nog een fout: een cursor aanpassen, of zelf ‘doorgaan’ berekenen. Gebruik exact de cursor die je ontvangt voor het volgende verzoek, zonder te knutselen. Ook bij retries geldt: opnieuw dezelfde pagina ophalen vereist dezelfde cursor en dezelfde parameters. Sla pas een nieuwe cursor op nadat je de vorige batch verwerkt hebt. Offset-gebaseerde pagina’s zijn eenvoudiger te herhalen, maar door tussentijdse datawijzigingen kun je soms verschoven of dubbele resultaten krijgen. Houd ook rekening met API-rate limits bij herhaalde verzoeken.

Verder let je op de limiet, time-outs en hoeveel de client in één keer vasthoudt. Alles steeds eerst ophalen en dan verwerken, maakt geheugenverbruik onnodig groot. Verwerk wat kan per pagina en houd het aantal gelijktijdige verzoeken beheersbaar. Log genoeg om fouten terug te zoeken: denk aan filterwaarden, sortering, cursorversie en eventueel paginanummer. Laat persoonsdata uit logging als het niet nodig is. Test ook scenario’s met lege responses, dubbele sorteerwaarden, verlopen cursors en het muteren van records terwijl je ze net ophaalt. Lees meer over logging en foutafhandeling bij automatiseringen.

Veelgestelde vragen

Hoe geef ik paginering aan met HTTP Link-headers?

HTTP Link-headers bieden een manier om direct een volgende of vorige pagina aan te wijzen door een URL in de response te plaatsen. Je client hoeft dan geen parameters samen te stellen, maar volgt gewoon de link met rel="next" wanneer die bestaat.

  • Alleen links meesturen die op dat moment beschikbaar zijn, bijvoorbeeld next of prev.
  • Je client hoort de hele link te gebruiken, zonder zelf parameters te wijzigen.
  • Documenteer welke relaties de API toestaat en wat het betekent als er geen ‘next’ meer is.

Zo hoef je minder te weten van de precieze URL-structuur. Maar de precieze inhoud van de Link-header moet wel in de documentatie staan.

Hoe werkt achterwaartse cursorpaginering?

Je haalt hiermee de records op die vóór een bekende positie in de volgorde zitten. Daarvoor bevat de cursor de sorteerwaarden van het eerste item op je huidige pagina. De query gebruikt dan de omgekeerde vergelijking en geeft het gevraagde aantal resultaten terug in achterwaartse volgorde.

  • Draai de lijst zo nodig om voordat je hem teruggeeft en houd de zichtbare volgorde gelijk.
  • Gebruik een eigen cursor of navigATIElink voor je ‘vorige’ pagina.
  • Test heen-en-terug bladeren zorgvuldig, zodat je geen resultaten overslaat of dubbelt.

Leg vast of de cursor naar het eerste of het laatste record op de pagina wijst; daarmee stuur je namelijk de queryrichting.

Welke HTTP-statuscode gebruik ik voor een ongeldige of verlopen cursor?

Gebruik bij een ontbrekende, kapotte of ongeschikte cursor bijna altijd HTTP 400. Bij een cursor die wel ooit geldig was maar niet meer werkt, kun je ook HTTP 410 kiezen, als je expliciet wilt aangeven dat deze voorgoed niet meer bruikbaar is.

  • Geef altijd een duidelijke foutcode, zoals invalid_cursor of cursor_expired.
  • Schrijf erbij of de client vanaf het begin moet herstarten.
  • Laat geen gevoelige informatie in foutmeldingen achter.

Kies één vaste aanpak en leg die goed uit, zodat clients weten hoe om te gaan met foutcodes.

Hoe bepaal ik een goede standaard- en maximumpaginagrootte voor een API?

Meet met echte API-calls en tests hoe groot je standaard en maximale paginagrootte moeten zijn. Kijk naar het effect op server, database en de client. Een goede standaardwaarde geeft in de praktijk zonder vertraging een bruikbaar resultaat; het maximum voorkomt misbruik en pieken.

  • Test met verschillende aantallen: responstijd, caching, geheugen en hoeveel rijen je query echt leest.
  • Check filters en datavolume die je in productie verwacht, zodat je geen vertekend beeld krijgt.
  • Leg vast wat er gebeurt als iemand de limit boven je maximum zet, bijvoorbeeld dat je afkapt of een foutmelding terugstuurt.

Er bestaat geen magisch getal. Houd de vinger aan de pols en stel je instellingen bij als het gebruik verandert.

Hoe test ik of paginering geen records overslaat of dubbel teruggeeft?

Haalt je client alle pagina’s na elkaar op, dan kun je controleren of de volledige, gesorteerde dataset klopt met wat je verwacht. Kijk niet alleen naar het aantal, maar naar de exacte volgorde en id’s.

  • Zorg dat er testdata is met dubbele sorteersleutels, lege pagina’s en precies op de grens van paginagroottes.
  • Check dat de ene pagina logisch op de volgende aansluit en dat het ‘einde’ goed wordt herkend.
  • Probeer ook met foutieve cursors, verschillende filters en sorteeropties.
  • Test verder wat er gebeurt als tussen twee pagina’s data verandert of verdwijnt.

De subtiele fouten komen meestal pas aan het licht als je zulke situaties expliciet naloopt.

Foto: Pixabay

Portret van Maarten

Maarten

Freelance developer in Nijmegen

Even kennismaken?

Vertel kort wat er speelt. Dan hoor je wat er kan, wat ik anders zou doen en waar AI bij jou wél en niet iets toevoegt. Vrijblijvend.

Het kantoor in Nijmegen
© 2026 maarten.online Sitemap Privacy Algemene voorwaarden
Het kantoor in Nijmegen

Maarten.

Freelance developer in Nijmegen. Liever direct contact? Dat kan ook.

Kennismaken

Laat je gegevens achter, dan kijken we of het klikt. Vrijblijvend en zonder verkooppraat.

Maarten

Stuur een bericht via WhatsApp

Hoi! Waar kan ik je mee helpen?

nu