API's geven je niet duizenden resultaten in een keer terug; dat zou traag en onpraktisch zijn. In plaats daarvan krijg je de data in pagina's. Wie alleen de eerste pagina verwerkt, mist het grootste deel van de data, een klassieke en stille bug. In dit artikel leer je hoe je betrouwbaar door alle resultaten loopt.
Hoe paginering werkt
Het patroon is consistent over vrijwel alle Workspace-API's.
- Je doet een list-call met een paginagrootte.
- Het antwoord bevat de resultaten plus een
nextPageToken. - Je doet de volgende call met die token als
pageToken. - Je herhaalt totdat het antwoord geen
nextPageTokenmeer bevat.
Het stopsignaal van je lus
Een ontbrekende nextPageToken betekent dat je de laatste pagina hebt bereikt. Zolang de token aanwezig is, is er meer data. Controleer hier expliciet op; tel nooit het aantal items om te bepalen of je klaar bent.
De lus correct schrijven
De veiligste vorm is een lus die doorgaat zolang er een token is.
gebruikers = []
page_token = None
while True:
response = service.users().list(
customer='my_customer', maxResults=200, pageToken=page_token
).execute()
gebruikers.extend(response.get('users', []))
page_token = response.get('nextPageToken')
if not page_token:
break
Let op de response.get('users', []): een pagina kan een lege lijst teruggeven en toch nog een token bevatten, dus blijf doorlopen zolang de token er is.
Gebruik de list_next-helper
De Python-client (google-api-python-client) biedt voor elke list-methode een bijbehorende list_next-helper. Je geeft het vorige request en de vorige response mee, en de helper bouwt automatisch het volgende request met de juiste token, of geeft None terug als je klaar bent. Dat maakt je code korter en minder foutgevoelig.
Met de helper ziet dezelfde lus er zo uit:
gebruikers = []
request = service.users().list(customer='my_customer', maxResults=200)
while request is not None:
response = request.execute()
gebruikers.extend(response.get('users', []))
request = service.users().list_next(request, response)
Paginagrootte afstemmen
Met pageSize of maxResults bepaal je hoeveel items er per pagina terugkomen. Dit is een afweging tussen latency per call en het totaal aantal calls.
| Doel | Keuze | Waarom |
|---|---|---|
| Snel beginnen met verwerken | Kleinere paginagrootte | Lagere latency per call, je ziet eerder data |
| Minimaal aantal calls | Maximale paginagrootte | Minder rondreizen bij een grote set |
De toegestane maximumwaarde verschilt per API en per methode. De Directory API users.list staat bijvoorbeeld maximaal 500 toe, andere endpoints hanteren andere grenzen. Controleer de referentiedocumentatie van de specifieke methode.
Valkuilen vermijden
Bewaar page tokens niet voor later
Page tokens zijn kortstondig en kunnen verlopen of ongeldig worden, zeker als de onderliggende data verandert. Doorloop een resultaatset in een aaneengesloten reeks calls, niet verspreid over uren met opgeslagen tokens.
Een complete doorloop
Zo loop je door alle pagina's
- Doe de eerste list-call met de gewenste paginagrootte.
- Verwerk de items uit de response direct of verzamel ze.
- Lees de
nextPageTokenuit het antwoord. - Is er een token? Doe de volgende call ermee. Geen token? Stop.
- Houd rekening met rate limits door backoff tussen pagina's als je veel calls doet.
Veelgestelde vragen
Wat gebeurt er als de data verandert tijdens het pagineren?
Je kunt items missen of dubbel zien als de onderliggende data wijzigt tussen pagina's. Wil je een consistente momentopname, gebruik dan waar mogelijk een sync-mechanisme of een API die snapshots ondersteunt.
Is de paginagrootte gegarandeerd?
Nee, het is een maximum, geen garantie. Een pagina kan minder items bevatten dan gevraagd. Gebruik altijd de token, niet het aantal items, om te bepalen of je klaar bent.
Heten alle parameters hetzelfde in elke API?
De meeste Workspace-API's gebruiken pageToken en nextPageToken, maar de paginagrootte heet soms maxResults (Directory API) en soms pageSize (Drive, Calendar). Controleer de documentatie per API.
Hoe ga ik om met heel grote sets?
Verwerk pagina voor pagina in plaats van alles in het geheugen te verzamelen. Streamend verwerken voorkomt geheugenproblemen bij tienduizenden items.
Waarom krijg ik soms een lege pagina met toch een token?
Sommige API's, waaronder de Directory API, geven af en toe een pagina zonder items terug terwijl er nog een nextPageToken is. Blijf daarom doorlopen zolang de token aanwezig is, ook bij een lege resultaatlijst.
Kan ik pagina's parallel ophalen?
Nee. Elke volgende token komt pas beschikbaar nadat je de vorige pagina hebt opgehaald, dus pagineren is per definitie sequentieel. Parallelliseer eventueel de verwerking, niet het ophalen.
Met correcte paginering verwerk je elke resultaatset volledig, hoe groot ook, zonder stille datalekken in je integratie.