Pagination

Une liste ne renvoie jamais tout d'un coup. Elle renvoie une page, triée par date de changement puis par id, et te dit s'il en reste une autre. Une page coûte un crédit, quel que soit son nombre d'objets.

Les paramètres d'une liste

Un paramètre qu'une liste ne connaît pas, ou un limit hors de 1 à 200, est refusé en 400 VALIDATION, et l'appel reste facturé.

Suivre les pages

Chaque réponse a la même forme :

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0yNVQwOToxMjowMC4wMDBafDQzMTg"
}

Tant que has_more vaut true, rappelle la même route avec cursor égal à next_cursor. Sur la dernière page, next_cursor vaut null. Le curseur est opaque : il encode la position du dernier objet reçu, ne le fabrique pas. Garde les mêmes filtres (since, student_id, status, include_deleted) d'une page à l'autre.

Ces boucles utilisent la fonction call de Écrire un script :

Python

def read_all(path, **filters):
    items, cursor = [], None
    while True:
        params = {**filters, "limit": 200}
        if cursor:
            params["cursor"] = cursor
        page = call("GET", path, params=params)
        items += page["data"]
        if not page["has_more"]:
            return items
        cursor = page["next_cursor"]

JavaScript

async function readAll(path, filters = {}) {
  const items = [];
  let cursor;
  do {
    const query = new URLSearchParams({ ...filters, limit: "200" });
    if (cursor) query.set("cursor", cursor);
    const page = await call("GET", `${path}?${query}`);
    items.push(...page.data);
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
  return items;
}

Ne relire que les changements

Après une première lecture complète, garde le plus grand updated_at reçu. Passe-le dans since à la lecture suivante, avec include_deleted=true : tu reçois ce qui a changé, suppressions comprises. Sans lui, une lecture par since ne voit jamais un objet supprimé.

Le test est inclusif. L'objet qui porte exactement cette date revient une deuxième fois, et un objet modifié pendant ta lecture peut revenir plus loin. Dédoublonne par id et garde le dernier reçu.

Le updated_at d'un élève bouge aussi à chaque connexion de l'élève. Une synchro quotidienne revoit donc les élèves connectés depuis la veille, sans changement visible.

Objets supprimés

Sans include_deleted, un objet supprimé disparaît de la liste. Avec include_deleted=true, il revient avec un deleted_at renseigné : retire-le de ta copie. Le champ n'existe que sur les ressources qui le portent, pas sur Student : un élève qui quitte ton suivi se lit dans GET /students/departures, décrit dans la référence.