Pagination

L’enveloppe#

Une liste paginée répond :

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

• has_more est un fait, pas une supposition : l’API lit une ligne de plus que demandé. Il n’y a pas de total.
• next_cursor n’est présent que si has_more vaut true. Renvoyez-le comme cursor, avec les mêmes paramètres, pour la page suivante. Le flux de modifications fait exception : il renvoie un curseur sur chaque page, la dernière comprise, pour que vous puissiez reprendre à partir de là (voir suivre le flux).
• limit est la taille de page utilisée.

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

Tailles de page#

limit vaut 50 par défaut. Au-delà du maximum de votre formule, c’est une erreur, 400 invalid_parameter, jamais une troncature silencieuse : servir discrètement 20 lignes à qui en demandait 100, c’est lui faire croire qu’il a lu toute une liste alors qu’il n’en a lu que la première page.

Les mêmes chiffres figurent dans max_page_size de GET /v1/plans et de GET /v1/key. La clé d’un compte sans formule reçoit 402 subscription_required sur chaque liste, quelle que soit la limite.

Curseurs#

• Un curseur contient la clé de tri et l’id de la dernière ligne. Traitez-le comme opaque : son format peut changer.
• Un curseur appartient à la liste et à l’ordre de tri dont il provient. Réutilisé ailleurs (un autre sort, une autre route), il donne 400 invalid_cursor, et vous recommencez sans curseur ; l’API ne repart jamais discrètement de la première page.
• Gardez les mêmes filtres pendant la pagination. Le curseur ne les mémorise pas : les changer en cours de route vous fait parcourir une autre liste à partir de l’endroit où l’ancienne s’était arrêtée.
• Une page à la fois. Des requêtes parallèles n’accélèrent pas le parcours d’un curseur et consomment votre limite par seconde.

Ordres de tri#

Quelles listes sont paginées#

Parcourir toute une liste#

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"]