Paginação

Todas as listas desta API se leem da mesma maneira: percorre-se uma coleção página a página, incluindo as entregas.

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

A resposta é { "data": [...], "nextCursor": string | null }.

Sem intervalo de tempo

Não há from nem to. Um registo é alterado no lugar (uma correção, um tombstone), por isso percorre-se a coleção e reconcilia-se, em vez de se pedir uma janela dela. Para ler uma semana de entregas, percorra deliveries e guarde os registos cujo data.timestamp cai dentro dessa semana.

Ordenação

Da alteração mais antiga para a mais recente: por sequence ascendente, a posição da última alteração de cada registo no fluxo. Compare dois valores de sequence; não faça aritmética com um.

Percorrer as páginas

nextCursor é null na última página e uma cadeia de caracteres nas restantes. Devolva-o intacto: é uma posição opaca, não um documento para analisar, e o seu conteúdo vai mudar sem aviso.

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

Um percurso é um snapshot coerente. A primeira página fixa a posição no fluxo, e todas as páginas seguintes são respondidas a partir dessa mesma posição. Os registos escritos enquanto está a paginar não deslocam as páginas debaixo de si. Vê-os no percurso seguinte.

O cursor está ligado ao restaurante, à coleção e ao limite. Mude o tamanho da página a meio do percurso e a resposta é 400: escolha um limite e mantenha-o durante todo o percurso.

Manter uma cópia atualizada

De momento não há parâmetro since. Uma atualização é outro percurso, e reconcilia-se com o que já tem:

• Indexe pelo id dentro de uma coleção, e substitua quando o sequence que recebe for maior do que o que guardou.
• Respeite os tombstones. deleted: true é a instrução de apagar; aplicá-la é a única forma de a sua cópia deixar de divergir.
• Conte com chegadas tardias. Um dispositivo que esteve offline durante o serviço envia os dados quando volta a ligar-se, por isso um registo pode aparecer depois de um percurso que teria abrangido o seu data.timestamp. Faça os relatórios por capturedAt e sincronize por receivedAt.

Uma página vazia não é prova de que nada aconteceu. Veja a nota sobre a completude.