Aller au contenu principal

Pagination

Disponible avecProResearch

Les routes qui peuvent renvoyer beaucoup de données les renvoient par pages. L'API utilise trois types de pagination, et chaque route en utilise un. Le type est le même partout où il apparaît, et la réponse indique toujours s'il y a une suite. La recherche n'est pas paginée : elle renvoie les limit meilleurs résultats.

Pagination par décalage : le texte d'un document​

GET /documents/:id renvoie le texte d'un document par morceaux d'au plus maxChars caractères (12 000 par défaut, 20 000 au maximum). Passez le nextOffset d'une réponse comme offset dans la suivante, jusqu'à ce que nextOffset soit 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;
}

La réponse contient aussi totalChars (la longueur totale) et truncated, qui vaut true tant qu'il reste du texte.

Pagination par curseur : passages, transcriptions, projets​

Un curseur est un signet que l'API vous donne. Ne le construisez pas vous-même. Renvoyez-le tel quel.

RouteCurseur à envoyerD'où vient le suivantLimite
GET /documents/:id/chunkscursor (un nombre)nextCursorlimit, 100 au maximum
GET /documents/:id/transcriptcursor (une chaîne)nextCursorlimit, 500 au maximum
GET /projectscursor (une chaîne)nextCursorlimit, 50 au maximum

Le premier appel n'a pas de curseur. Continuez d'appeler avec le dernier nextCursor jusqu'à ce qu'il soit null ou absent.

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

La réponse contient la page de projets et, quand il y en a davantage, nextCursor (abrégé ici) :

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

La page suivante renvoie cette valeur sous le nom cursor :

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

Numéros de page : marque-pages et collections​

Les anciennes routes /api/v1/bookmarks et /api/v1/collections utilisent page (à partir de 1) et limit (100 au maximum, 20 par défaut). La liste des marque-pages répond avec bookmarks, total, page, limit et hasMore. Demandez la page suivante tant que hasMore vaut true.

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

Conseils​

  • Chaque page est une requête et compte dans vos limites. Utilisez la plus grande limit que la route autorise quand vous avez besoin de tout.
  • Les pages se lisent l'une après l'autre. Ne les envoyez pas en parallèle avec le même curseur.
  • Arrêtez-vous quand le curseur ou nextOffset vaut null, ou quand hasMore vaut false.
Dernière mise à jour le