Zum Hauptinhalt springen

Paginierung

Verfügbar inProResearch

Routen, die viele Daten liefern können, geben sie seitenweise zurück. Die API kennt drei Arten von Paginierung, und jede Route nutzt eine davon. Die Art ist überall gleich, wo sie vorkommt, und die Antwort sagt dir immer, ob es mehr gibt. Die Suche ist nicht paginiert: Sie liefert die besten limit Ergebnisse.

Offset-Paginierung: Dokumenttext​

GET /documents/:id liefert den Text eines Dokuments in Stücken von bis zu maxChars Zeichen (Standard 12.000, höchstens 20.000). Übergib nextOffset aus einer Antwort als offset in der nächsten, bis nextOffset den Wert null hat.

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

Ebenfalls in der Antwort: totalChars (die Gesamtlänge) und truncated, das true ist, solange noch Text übrig ist.

Cursor-Paginierung: Chunks, Transkripte, Projekte​

Ein Cursor ist ein Lesezeichen, das dir die API gibt. Baue ihn nicht selbst. Sende ihn unverändert zurück.

RouteCursor, den du sendestWoher der nächste kommtLimit
GET /documents/:id/chunkscursor (eine Zahl)nextCursorlimit, höchstens 100
GET /documents/:id/transcriptcursor (ein String)nextCursorlimit, höchstens 500
GET /projectscursor (ein String)nextCursorlimit, höchstens 50

Der erste Aufruf hat keinen Cursor. Rufe weiter mit dem letzten nextCursor auf, bis er null ist oder fehlt.

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

Die Antwort enthält die Seite mit Projekten und, wenn es mehr gibt, nextCursor (hier gekürzt):

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

Die nächste Seite sendet diesen Wert als cursor zurück:

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

Seitennummern: Lesezeichen und Sammlungen​

Die älteren Routen /api/v1/bookmarks und /api/v1/collections nutzen page (ab 1) und limit (höchstens 100, Standard 20). Die Lesezeichenliste antwortet mit bookmarks, total, page, limit und hasMore. Fordere die nächste page an, solange hasMore true ist.

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

Tipps​

  • Jede Seite ist eine Anfrage und zählt auf deine Limits. Nutze das größte limit, das die Route erlaubt, wenn du alles brauchst.
  • Seiten werden nacheinander gelesen. Sende sie nicht parallel mit demselben Cursor.
  • Höre auf, wenn der Cursor oder nextOffset null ist oder wenn hasMore false ist.
Letztes Update am