Paginering

De structuur#

Een gepagineerde lijst antwoordt:

{
  "data": [
    "…"
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJzIjoic3Vic2lkaWVzOnVwZGF0ZWQiLCJrIjoi…",
    "limit": 50
  },
  "meta": {
    "request_id": "req_…",
    "warnings": []
  }
}

• has_more is een feit, geen gok: de API leest één rij meer dan je vroeg. Er is geen totaal.
• next_cursor is er alleen als has_more true is. Geef hem terug als cursor, met dezelfde parameters, voor de volgende pagina. De change feed is de uitzondering: die geeft op elke pagina een cursor, ook op de laatste, zodat je van daar verder kunt pollen (zie de feed volgen).
• limit is de gebruikte paginagrootte.

$ curl "https://api.subsido.be/v1/subsidies?status=open&sort=updated&limit=100&cursor=eyJzIjoic3Vic2lkaWVzOnVwZGF0ZWQiLCJrIjoi…" \  -H "Authorization: Bearer sb_live_..."

Paginagrootte#

limit is standaard 50. Boven het maximum van je plan is het een fout, 400 invalid_parameter, nooit een stille inkorting: wie 100 rijen vraagt en er zonder melding 20 krijgt, denkt al snel dat hij een hele lijst gelezen heeft, terwijl het maar de eerste pagina was.

Dezelfde cijfers staan in max_page_size van GET /v1/plans en GET /v1/key. Een sleutel van een account zonder plan krijgt op elke lijst 402 subscription_required, welke limit je ook vraagt.

Cursors#

• Een cursor bevat de sorteersleutel en het id van de laatste rij. Behandel hem als ondoorzichtig: het formaat kan veranderen.
• Een cursor hoort bij de lijst en de sorteervolgorde waar hij vandaan komt. Tegen een andere gebruikt (een andere sort, een andere route) geeft hij 400 invalid_cursor, en begin je opnieuw zonder cursor; de API begint nooit stilzwijgend weer bij pagina één.
• Houd de filters gelijk terwijl je pagineert. De cursor onthoudt ze niet, dus als je ze onderweg wijzigt, blader je door een andere lijst vanaf het punt waar de oude stopte.
• Vraag één pagina tegelijk op. Pagina’s parallel ophalen maakt het doorlopen van een cursor niet sneller en verbruikt wel je rate limit per seconde.

Sorteervolgordes#

Welke lijsten pagineren#

Een hele lijst doorlopen#

import os, requests

def all_open_measures():
    params = {"status": "open,continuous,forthcoming", "sort": "updated", "limit": 100}
    headers = {"Authorization": f"Bearer {os.environ['SUBSIDY_API_KEY']}"}
    while True:
        r = requests.get("https://api.subsido.be/v1/subsidies", params=params, headers=headers, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page["data"]
        if not page["pagination"]["has_more"]:
            return
        params["cursor"] = page["pagination"]["next_cursor"]