Paginació de l'API

Els endpoints de llistat paginen. Els paràmetres exactes de query i la forma de resposta per endpoint estan documentats a la referència OpenAPI - no estandarditzem en tots perquè alguns (logs de lliurament, logs d'auditoria) necessiten comportament estil cursor mentre altres (posts, comentaris) funcionen bé amb offset simple.

El cas comú es veu així.

Patró comú

GET /api/v1/some-resource?limit=50&offset=0

Altres paràmetres comuns: success (filtre booleà sobre logs de lliurament), filtres de data (created_after, created_before), cerca/ordre.

Iterar amb limit + offset

async function* allItems<T>(url: string, init: RequestInit, limit = 100): AsyncGenerator<T> {
  let offset = 0;
  while (true) {
    const u = new URL(url);
    u.searchParams.set("limit", String(limit));
    u.searchParams.set("offset", String(offset));
    const res = await fetch(u, init);
    const items: T[] = await res.json();
    for (const item of items) yield item;
    if (items.length < limit) break;
    offset += limit;
  }
}

Caveats

• Iterar un dataset que canvia ràpid amb offset és race-condition-prone. Els nous elements inserits al començament desplacen els offsets, així que saltaràs o duplicaràs. Per a exportacions d'un sol ús, captura un snapshot via queries filtrades (created_before=<ara>) en el seu lloc.
• La paginació per cursor està al full de ruta per als endpoints d'alta escriptura (logs de lliurament, logs d'auditoria) on l'offset es torna costós.

Per al detall per endpoint (limit per defecte, limit màxim, filtres addicionals), la referència OpenAPI és canònica.