# Paginering afhandelen in Workspace API-responses

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 `nextPageToken` meer bevat.

:::info title="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.

```python
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.

:::tip title="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:

```python
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

:::warn title="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

:::howto title="Zo loop je door alle pagina's"
1. Doe de eerste list-call met de gewenste paginagrootte.
2. Verwerk de items uit de response direct of verzamel ze.
3. Lees de `nextPageToken` uit het antwoord.
4. Is er een token? Doe de volgende call ermee. Geen token? Stop.
5. Houd rekening met rate limits door **backoff** tussen pagina's als je veel calls doet.
:::

## Veelgestelde vragen

:::faq
### 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.