Pagination

Chaque endpoint de liste renvoie un tableau items et un objet meta. Deux modes partagent le même endpoint : la pagination par offset par défaut, la pagination par curseur dès que vous envoyez un cursor. Une page numérotée porte aussi le next_cursor qui la prolonge : un parcours par curseur commence donc par une requête ordinaire. meta vous indique quel mode a répondu : current_page en mode offset, prev_cursor en mode curseur.

Paramètres

Les filtres dépendent de la ressource, ils ne sont pas globaux. Sur GET /payments :

Pagination par offset

Le mode par défaut. Demandez un numéro de page, vous recevez un meta qui indique combien il y en a au total, et d'où repartir avec un curseur :

curl "https://api.wajub.com/payments?per_page=2&status=succeeded" \
-H "Authorization: $WAJUB_API_KEY"

has_more indique si une page suit celle-ci, et next_cursor est le curseur du dernier élément de la page : null sur la dernière page. Les deux sont là pour vous permettre de continuer avec un curseur. Pour rester en mode offset, ignorez-les.

Bouclez jusqu'à ce que current_page atteigne last_page. Utilisez la plus grande taille de page possible, 100, pour qu'un historique de 137 éléments tienne en deux requêtes au lieu de six :

async function allPayments(filters = {}) {
const all = [];
let page = 1;

while (true) {
  const params = new URLSearchParams({ ...filters, per_page: '100', page: String(page) });
  const res = await fetch(`https://api.wajub.com/payments?${params}`, {
    headers: { Authorization: process.env.WAJUB_API_KEY },
  });
  const { items, meta } = await res.json();

  all.push(...items);

  if (page >= meta.last_page) break;
  page += 1;
}

return all;
}

Pagination par curseur

Les pages par offset se décalent quand de nouveaux éléments arrivent pendant votre parcours, et ralentissent sur un long historique. Les curseurs évitent les deux : passez cursor et chaque page est ancrée sur le dernier élément que vous avez vu.

Vous n'avez aucun curseur à envoyer à la première requête : commencez donc sans. La première page est une page numérotée, et son meta porte next_cursor. Renvoyez-le comme cursor et le parcours continue en mode curseur, juste après le dernier élément reçu, sans élément sauté ni servi deux fois. Cela vaut depuis n'importe quelle page numérotée, pas seulement la première.

meta change de forme en mode curseur. current_page, last_page et total disparaissent, remplacés par :

Renvoyez next_cursor comme cursor et arrêtez-vous quand has_more vaut false :

async function* streamPayments() {
// Pas de curseur à la première requête : cette page porte déjà next_cursor.
let cursor = null;

do {
  const params = new URLSearchParams({ per_page: '100' });

  if (cursor) params.set('cursor', cursor);

  const res = await fetch(`https://api.wajub.com/payments?${params}`, {
    headers: { Authorization: process.env.WAJUB_API_KEY },
  });
  const { items, meta } = await res.json();

  yield* items;
  cursor = meta.has_more ? meta.next_cursor : null;
} while (cursor);
}

Endpoints et modes pris en charge

Le mode curseur est disponible partout où la liste a un tri stable sur created_at. Trois listes ne proposent que l'offset : leur meta n'a ni next_cursor ni has_more.

GET /invoices et GET /links acceptent sort_by et sort_dir. Le mode curseur a besoin de leur ordre par défaut, du plus récent au plus ancien : avec un autre tri, cursor est ignoré et la page numérotée ne porte ni next_cursor ni has_more. Paginez alors par numéro.