Paginierung & Zeiträume

Wie Sie Lieferungen und Collection-Datensätze mit einem undurchsichtigen Cursor durchlaufen und warum das eine einen Zeitraum nimmt und das andere nicht.

Zwei Endpunkte paginieren, und sie tun es mit Absicht unterschiedlich:

Liste	Zeitraum	Sortierung	Cursor ist gebunden an
Lieferungen	`from` und `to`, Pflicht, höchstens 366 Tage	Neueste zuerst	Den Zeitraum, den Sie angefragt haben
Collection-Datensätze	keiner — Sie durchlaufen die ganze Collection	Älteste Änderung zuerst	Restaurant, Collection und `limit`

Beide antworten mit { "data": [...], "nextCursor": string | null }, beide deckeln limit bei 100 mit einem Standard von 50, und beide wollen den Cursor unverändert zurück. Der Rest dieser Seite ist die Lieferliste; die Collections-Seite behandelt die andere.

Lieferungen sind unveränderlich und nach Datum interessant, sie nehmen also einen Zeitraum. Collection-Datensätze ändern sich an Ort und Stelle, ein Zeitraum über ihnen wäre also eine Lüge — Sie durchlaufen die Collection und gleichen ab.

Die Lieferliste

Sie nimmt einen verpflichtenden, ausdrücklichen Zeitraum und gibt eine Seite plus einen undurchsichtigen Cursor zurück.

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

Parameter	Pflicht	Regeln
`from`	ja	Millisekunden seit der Epoche, als Zeichenkette aus Ziffern. Einschließlich.
`to`	ja	Millisekunden seit der Epoche, als Zeichenkette aus Ziffern. Einschließlich.
`limit`	nein	1 bis 100. Standard ist 50.
`cursor`	nein	Der `nextCursor` der vorherigen Seite, wortgleich.

to muss größer oder gleich from sein, und die Spanne darf höchstens 366 Tage betragen. Alles andere antwortet 400. Der Zeitraum ist Pflicht statt vorbelegt, weil eine Vorbelegung genau der Weg ist, auf dem eine Integration still und leise anfängt, jede Nacht ein Jahrzehnt an Datensätzen erneut zu lesen.

Sortierung

Neueste zuerst: absteigend nach occurredAt, dann absteigend nach id, um Gleichstand aufzulösen. Zwei Lieferungen, die in derselben Millisekunde erfasst wurden, haben damit eine stabile, wiederholbare Reihenfolge, und genau das macht den Cursor tragfähig.

Die Seiten durchlaufen

nextCursor ist auf der letzten Seite null und sonst eine Zeichenkette. Geben Sie ihn unverändert zurück — er ist eine base64url-kodierte Position und kein Dokument zum Parsen, und sein Innenleben ändert sich ohne Ankündigung.

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);
}

Halten Sie from und to über jede Seite eines Durchlaufs hinweg identisch. Der Cursor kodiert eine Position innerhalb des Zeitraums, den Sie angefragt haben; den Zeitraum mitten im Durchlauf zu ändern ist keine unterstützte Anfrage und gibt Ihnen nicht, was Sie erwarten.

Inkrementell abfragen

Lieferungen sind unveränderlich, sobald sie erfasst sind, eine inkrementelle Abfrage ist also unkompliziert: Merken Sie sich den occurredAt des neuesten Datensatzes, den Sie gespeichert haben, und verwenden Sie ihn als nächstes from.

Zwei Details, die einzubauen sich lohnt:

Überlappen Sie absichtlich. Beginnen Sie das nächste Fenster ein Stück vor dem letzten Datensatz, den Sie gesehen haben — eine Stunde reicht vollkommen — und entfernen Sie Duplikate anhand von id. Ein Gerät, das während des Betriebs offline war, lädt hoch, sobald es sich wieder verbindet; eine Lieferung kann also nach einer Abfrage sichtbar werden, die ihren Zeitstempel bereits abgedeckt hatte.
Gehen Sie nie über 366 Tage hinaus. Wenn Ihr Job lange nicht gelaufen ist, durchlaufen Sie die Lücke in jahreslangen Fenstern, statt alles auf einmal anzufragen.

Eine leere Seite ist kein Beweis, dass nichts passiert ist — siehe die Anmerkung zur Vollständigkeit.