Paginación de la API

Los endpoints de listado paginan. Los parámetros exactos de query y la forma de respuesta por endpoint están documentados en la referencia OpenAPI - no estandarizamos en todos porque algunos (logs de entrega, logs de auditoría) necesitan comportamiento estilo cursor mientras otros (posts, comentarios) funcionan bien con offset simple.

El caso común se ve así.

Patrón común

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

Otros parámetros comunes: success (filtro booleano sobre logs de entrega), filtros de fecha (created_after, created_before), búsqueda/orden.

Iterar con 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 cambia rápido con offset es race-condition-prone. Los nuevos elementos insertados al principio desplazan los offsets, así que saltarás o duplicarás. Para exportaciones de un solo uso, captura un snapshot vía queries filtradas (created_before=<ahora>) en su lugar.
• La paginación por cursor está en la hoja de ruta para los endpoints de alta escritura (logs de entrega, logs de auditoría) donde el offset se vuelve costoso.

Para el detalle por endpoint (limit por defecto, limit máximo, filtros adicionales), la referencia OpenAPI es canónica.