Pagination et plages de temps

Deux endpoints paginent, et ils le font différemment à dessein :

Les deux répondent { "data": [...], "nextCursor": string | null }, les deux plafonnent limit à 100 avec 50 par défaut, et les deux veulent qu'on leur rende le curseur tel quel. Le reste de cette page porte sur la liste des livraisons ; la page des collections couvre l'autre.

Les livraisons sont immuables et intéressantes par date, elles prennent donc une plage. Les enregistrements de collection changent sur place, une plage sur eux serait donc un mensonge — vous parcourez la collection et vous réconciliez.

La liste des livraisons

Elle prend une plage de temps explicite et obligatoire et renvoie une page plus un curseur opaque.

GET /v1/restaurants/{restaurantId}/deliveries
  ?from=1787846400000
  &to=1788451200000
  &limit=50
  &cursor=eyJpZCI6…

to doit être supérieur ou égal à from, et l'étendue doit être d'au plus 366 jours. Tout le reste répond 400. La plage est obligatoire plutôt que définie par défaut, parce qu'une valeur par défaut est exactement ce qui fait qu'une intégration se met silencieusement à relire dix ans d'enregistrements toutes les nuits.

Tri

Les plus récentes d'abord : décroissant sur occurredAt, puis décroissant sur id pour départager. Deux livraisons enregistrées dans la même milliseconde ont donc un ordre stable et reproductible, et c'est ce qui rend le curseur fiable.

Parcourir les pages

nextCursor vaut null sur la dernière page et une chaîne de caractères sinon. Renvoyez-le tel quel — c'est une position encodée en base64url, pas un document à analyser, et ses entrailles changeront sans préavis.

async function* deliveries({ apiKey, restaurantId, from, to }) {
  const base = `https://api.backresto.com/v1/restaurants/${restaurantId}/deliveries`;
  let cursor = null;

  do {
    const url = new URL(base);
    url.searchParams.set('from', from);
    url.searchParams.set('to', to);
    url.searchParams.set('limit', '100');
    if (cursor !== null) {
      url.searchParams.set('cursor', cursor);
    }

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });
    if (!response.ok) {
      throw new Error(`BackResto ${response.status}`);
    }

    const page = await response.json();
    yield* page.data;
    cursor = page.nextCursor;
  } while (cursor !== null);
}

Gardez from et to identiques sur toutes les pages d'un parcours. Le curseur encode une position à l'intérieur de la plage que vous avez demandée ; changer la plage en cours de parcours n'est pas une requête prise en charge et ne vous donnera pas ce que vous attendez.

Interroger de façon incrémentale

Les livraisons sont immuables une fois enregistrées, l'interrogation incrémentale est donc simple : gardez l'occurredAt de l'enregistrement le plus récent que vous ayez stocké et utilisez-le comme prochain from.

Deux détails qui valent la peine d'être intégrés :

• Chevauchez délibérément. Commencez la fenêtre suivante un peu avant le dernier enregistrement que vous avez vu — une heure suffit largement — et dédupliquez sur id. Un appareil resté hors ligne pendant le service téléverse quand il se reconnecte, une livraison peut donc devenir visible après une interrogation qui couvrait déjà son horodatage.
• N'élargissez jamais au-delà de 366 jours. Si votre job n'a pas tourné depuis longtemps, parcourez l'écart par fenêtres d'un an plutôt que de tout demander d'un coup.

Une page vide n'est pas la preuve que rien ne s'est passé — voyez la note sur l'exhaustivité.