Paginering

Alle list-endpoints retourneren gepagineerde resultaten met cursor-based paginering. De SDK biedt twee manieren om hiermee te werken: handmatige cursors en async iterators.

Hoe het werkt

Elke gepagineerde response bevat een pagination object:

{
  "data": [ ... ],
  "pagination": {
    "total": 47,
    "limit": 20,
    "nextCursor": "eyJpZCI6InBhZ2VfMjAifQ=="
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-05-26T12:00:00Z" }
}

Veld	Beschrijving
`total`	Totaal aantal items
`limit`	Items per pagina (standaard 20, max 100)
`nextCursor`	Cursor voor de volgende pagina. `null` als er geen volgende pagina is

Methode 1 — Handmatige cursors

Gebruik list() met cursor parameter om pagina voor pagina op te halen:

import cms from './cms';

// Eerste pagina
const page1 = await cms.sites.list({ limit: 10 });
console.log(`${page1.data.length} van ${page1.pagination.total} sites`);

// Tweede pagina (als die er is)
if (page1.pagination.nextCursor) {
  const page2 = await cms.sites.list({
    limit: 10,
    cursor: page1.pagination.nextCursor,
  });
  console.log(`Pagina 2: ${page2.data.length} sites`);
}

Response pagina 1:

{
  "data": [
    { "id": "site_001", "name": "Site 1", "status": "published" },
    { "id": "site_002", "name": "Site 2", "status": "published" },
    { "id": "site_003", "name": "Site 3", "status": "draft" }
  ],
  "pagination": {
    "total": 47,
    "limit": 10,
    "nextCursor": "eyJpZCI6InNpdGVfMDEwIn0="
  },
  "meta": { "requestId": "req_pg1", "timestamp": "2026-05-26T12:00:00Z" }
}

Response laatste pagina:

{
  "data": [
    { "id": "site_045", "name": "Site 45", "status": "published" }
  ],
  "pagination": {
    "total": 47,
    "limit": 10,
    "nextCursor": null
  },
  "meta": { "requestId": "req_pg5", "timestamp": "2026-05-26T12:00:02Z" }
}

Alle items ophalen met een loop

import type { SiteSummary } from '@optimocms/sdk';

const allSites: SiteSummary[] = [];
let cursor: string | null = null;

do {
  const response = await cms.sites.list({ limit: 100, cursor: cursor ?? undefined });
  allSites.push(...response.data);
  cursor = response.pagination.nextCursor;
} while (cursor);

console.log(`Totaal: ${allSites.length} sites`);

Methode 2 — Async iterator (aanbevolen)

De SDK biedt een listAll() methode die automatisch alle pagina's doorloopt:

// Itereer over ALLE sites, ongeacht hoeveel pagina's er zijn
for await (const site of cms.sites.listAll()) {
  console.log(`${site.name} — ${site.domain}`);
}

De iterator haalt steeds de volgende pagina op wanneer de huidige leeg is. Je hoeft zelf geen cursors bij te houden.

Met filter parameters

// Alleen gepubliceerde pagina's
for await (const page of cms.pages.listAll('site_abc123', { status: 'published' })) {
  console.log(`${page.title} (${page.slug})`);
}

Vroegtijdig stoppen

// Stop na de eerste 5 resultaten
let count = 0;
for await (const site of cms.sites.listAll()) {
  console.log(site.name);
  if (++count >= 5) break;
}

Verzamelen in een array

// Alle items in een array
const allPages = [];
for await (const page of cms.pages.listAll('site_abc123')) {
  allPages.push(page);
}
console.log(`${allPages.length} pagina's gevonden`);

Paginering parameters

Parameter	Type	Standaard	Beschrijving
`limit`	`number`	`20`	Items per pagina (1–100)
`cursor`	`string`	—	Cursor van vorige response
`orderBy`	`string`	`updatedAt`	Sorteerveld (alleen bij pages)
`direction`	`'asc' \| 'desc'`	`'desc'`	Sorteerrichting (alleen bij pages)
`status`	`string`	—	Filter op status

Welke endpoints ondersteunen paginering?

Endpoint	`list()`	`listAll()`
`cms.sites.list()`	Ja	Ja
`cms.pages.list(siteId)`	Ja	Ja
`cms.media.list(siteId)`	Ja	Ja
`cms.shop.products.list(siteId)`	Ja	Ja
`cms.shop.orders.list(siteId)`	Ja	Ja
`cms.shop.coupons.list(siteId)`	Ja	Ja
`cms.booking.bookings.list(siteId)`	Ja	Ja
`cms.webhooks.list(siteId)`	Ja	Ja
`cms.webhooks.deliveries(siteId, webhookId)`	Ja	Ja
`cms.forms.submissions(siteId)`	Ja	Ja
`cms.reviews.list(siteId)`	Ja	Ja
`cms.recruitment.jobs.list(siteId)`	Ja	Ja

Voorbeeld: bulk update met rate limit respect

import { OptimoCMS, OptimoCMSError } from '@optimocms/sdk';

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,
  maxRetries: 5,
});

async function updateAllPageTitles(siteId: string, prefix: string) {
  let updated = 0;

  for await (const page of cms.pages.listAll(siteId)) {
    try {
      await cms.pages.update(siteId, page.id, {
        title: `${prefix} — ${page.title}`,
      });
      updated++;
      console.log(`[${updated}] ${page.title} bijgewerkt`);
    } catch (error) {
      if (error instanceof OptimoCMSError && error.status === 429) {
        console.log('Rate limit bereikt, SDK retry handelt dit af');
        throw error;
      }
      console.error(`Fout bij ${page.id}: ${error}`);
    }
  }

  console.log(`Klaar! ${updated} pagina's bijgewerkt.`);
}

Try it — curl equivalent:

# Eerste pagina
curl "https://api.optimocms.com/v1/sites?limit=10" \
  -H "X-Api-Key: jouw_api_key"

# Volgende pagina met cursor
curl "https://api.optimocms.com/v1/sites?limit=10&cursor=eyJpZCI6InNpdGVfMDEwIn0=" \
  -H "X-Api-Key: jouw_api_key"

Try it — MCP:

Haal alle pagina's op van site site_abc123.
→ De MCP server itereert automatisch door alle pagina's.

Volgende stappen

Foutafhandeling — Retry bij 429 en server errors
Authenticatie — Rate limits per tier
API Referentie — Alle endpoints

Paginering

On this page