Paginazione

Ogni elenco di questa API si legge allo stesso modo: si percorre una collezione pagina per pagina, consegne comprese.

GET /v1/restaurants/{restaurantId}/collections/{collection}/records
  ?limit=100
  &cursor=eyJpZCI6…

La risposta è { "data": [...], "nextCursor": string | null }.

Nessun intervallo di tempo

Non ci sono né from né to. Un record cambia sul posto (una correzione, un tombstone), quindi si percorre la collezione e si riconcilia anziché chiederne una finestra. Per leggere una settimana di consegne, percorra deliveries e tenga i record il cui data.timestamp cade all'interno della settimana.

Ordinamento

Dalla modifica più vecchia: in ordine crescente per sequence, la posizione dell'ultima modifica di ciascun record nel flusso. Confronti due valori di sequence; non ci faccia aritmetica sopra.

Percorrere le pagine

nextCursor è null sull'ultima pagina e una stringa altrimenti. Lo rimandi indietro intatto: è una posizione opaca, non un documento da analizzare, e la sua struttura interna cambierà senza preavviso.

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

  do {
    const url = new URL(base);
    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);
}

Un percorso è uno snapshot coerente. La prima pagina fissa la posizione nel flusso, e ogni pagina successiva viene servita a partire da quella stessa posizione. I record scritti mentre sta paginando non le spostano le pagine sotto i piedi. Li vedrà al percorso successivo.

Il cursore è legato al ristorante, alla collezione e al limit. Se cambia la dimensione della pagina a metà percorso risponde 400: scelga un limit e lo mantenga per tutto il percorso.

Tenere aggiornata una copia

Oggi non esiste un parametro since. Un aggiornamento è un altro percorso, e lo riconcilia con quello che già possiede:

• Usi id come chiave all'interno di una collezione, e sovrascriva quando il sequence che riceve è più alto di quello che ha memorizzato.
• Rispetti i tombstone. deleted: true è l'istruzione di cancellazione; applicarla è l'unico modo perché la sua copia smetta di divergere.
• Metta in conto gli arrivi tardivi. Un dispositivo che era offline durante il servizio carica i dati quando si riconnette, quindi un record può comparire dopo un percorso che avrebbe coperto il suo data.timestamp. Basi i report su capturedAt, la sincronizzazione su receivedAt.

Una pagina vuota non è la prova che non sia successo nulla. Veda la nota sulla completezza.