Saltar al contenido principal

Paginación

Disponible enProResearch

Las rutas que pueden devolver muchos datos los devuelven en páginas. La API usa tres tipos de paginación y cada ruta usa uno. El tipo es el mismo en todas partes donde aparece y la respuesta siempre te dice si hay más. La búsqueda no se pagina: devuelve los mejores limit resultados.

Paginación por desplazamiento: el texto de un documento​

GET /documents/:id devuelve el texto de un documento en trozos de hasta maxChars caracteres (por defecto 12 000, como máximo 20 000). Pasa nextOffset de una respuesta como offset en la siguiente, hasta que nextOffset sea null.

async function readDocument(id) {
  let offset = 0;
  let text = '';
  while (offset !== null) {
    const res = await fetch(
      `https://api.readsira.com/rest/v2/documents/${id}?offset=${offset}&maxChars=20000`,
      { headers: { Authorization: `Bearer ${process.env.READSIRA_KEY}` } },
    );
    const { data } = await res.json();
    text += data.text;
    offset = data.nextOffset;
  }
  return text;
}

También vienen en la respuesta totalChars (la longitud completa) y truncated, que es true mientras queda más texto.

Paginación por cursor: fragmentos, transcripciones, proyectos​

Un cursor es un marcador que te da la API. No lo construyas tú. Devuélvelo sin cambios.

RutaCursor que envíasDe dónde sale el siguienteLímite
GET /documents/:id/chunkscursor (un número)nextCursorlimit, como máximo 100
GET /documents/:id/transcriptcursor (una cadena)nextCursorlimit, como máximo 500
GET /projectscursor (una cadena)nextCursorlimit, como máximo 50

La primera llamada no lleva cursor. Sigue llamando con el último nextCursor hasta que sea null o falte.

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20"

La respuesta trae la página de proyectos y, cuando hay más, nextCursor (abreviado aquí):

{
  "success": true,
  "data": {
    "projects": ["..."],
    "nextCursor": "VALUE_FROM_THE_ANSWER"
  }
}

La página siguiente devuelve ese valor como cursor:

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Números de página: marcadores y colecciones​

Las rutas más antiguas /api/v1/bookmarks y /api/v1/collections usan page (desde 1) y limit (como máximo 100, por defecto 20). La lista de marcadores responde con bookmarks, total, page, limit y hasMore. Pide la siguiente page mientras hasMore sea true.

curl -G "https://api.readsira.com/api/v1/bookmarks" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -d page=2 -d limit=100

Consejos​

  • Cada página es una solicitud y cuenta para tus límites. Usa el limit más grande que permita la ruta cuando necesites todo.
  • Las páginas se leen una tras otra. No las envíes en paralelo con el mismo cursor.
  • Detente cuando el cursor o nextOffset sea null, o cuando hasMore sea false.
Última actualización en