LIVE · AUDIT-KETEN · EU-GEHOST
SYSTEEM · 99,99% UPTIME
v 1.0 ↗ GEMAAKT IN DE EU

Paginatie + idempotentie

Cursor-paginatie + Idempotency-Key-header voor de publieke NexBasira-API.

Paginatie + idempotentie

Cursor-paginatie op elk list-endpoint; Idempotency-Key op elk state-muterend endpoint. Twee patronen om één keer eigen te maken; elk endpoint volgt ze.

Cursor-paginatie

Alle list-endpoints (GET /api/v1/public/sessions, /evidence, /whiteboards, enz.) retourneren een envelope: 

{
  "data": [
    { /* resource */ },
    { /* resource */ }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMVQxNDoyMSswMDowMCJ9"
}

Hoe te pagineren

  1. Doe het eerste verzoek zonder cursor-param.
  2. Als has_more true is, geef next_cursor letterlijk mee als de cursor-query-param bij het volgende verzoek.
  3. Herhaal totdat has_more false is.
curl "https://app.nexbasira.com/api/v1/public/sessions?limit=25" \
  -H "Authorization: Bearer nb_sec_..."

# response includes next_cursor: "eyJjcmVhdGVkX2F0Ijo..."

curl "https://app.nexbasira.com/api/v1/public/sessions?limit=25&cursor=eyJjcmVhdGVkX2F0Ijo..." \
  -H "Authorization: Bearer nb_sec_..."

Limieten

ParamStandaardMax
limit25100

Hogere limit-waarden verminderen het aantal round-trips maar vergroten de payload-omvang + serialisatietijd per response. De standaard van 25 is geschikt voor UI-gebruik; nachtelijke batchjobs geven doorgaans 100 mee.

Cursor-vorm

De cursor is ondoorzichtig voor clients — het is een base64-gecodeerde JSON-blob die de positie in de onderliggende queryset codeert. Parse of construeer geen cursors; geef ze gewoon letterlijk door. De vorm is niet stabiel tussen API-versies.

Ordening

De standaardordening is created_at DESC (nieuwste eerst) voor elk list-endpoint. Dit is ook de volgorde waarin de cursor vooruitgaat — u loopt van meest recent naar oudst terwijl u pagineert.

SDK-helpers

Beide SDK's leveren een transparante async-iterator die voor u pagineert:

// @nexbasira/node
for await (const session of nb.sessions.list({ limit: 100 })) {
  // ...
}

// nexbasira (Python)
for session in nb.sessions.iter(limit=100):
    ...

Idempotentie

Elk state-muterend endpoint accepteert een Idempotency-Key-header. Geef een unieke sleutel (doorgaans een UUID) per logische operatie mee; een retry met dezelfde sleutel retourneert de gecachte response zonder de resource opnieuw aan te maken. 

curl -X POST https://app.nexbasira.com/api/v1/public/sessions \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Idempotency-Key: 01HGAB7T8X3PVT3HKEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Vehicle damage CL-2026-0042"}'

Cache-venster

Gecachte responses blijven 24 uur bestaan. Een replay na 24u met dezelfde sleutel maakt een nieuwe resource aan — behandel de sleutel alleen als geldig voor de duur van uw retry-lus.

Scoping

Sleutels zijn beperkt tot (credential, endpoint, method):

  • Een retry vanaf dezelfde credential naar hetzelfde endpoint met dezelfde sleutel retourneert de gecachte response.
  • Een andere credential die dezelfde sleutel gebruikt maakt een nieuwe resource aan (behandelt het als een verse call).
  • Dezelfde sleutel op een ander endpoint creëert een nieuwe resource (aparte cacheslot).

Wat er gecachet wordt

Alleen geslaagde responses (2xx). Een mislukt verzoek vervuilt de cache niet — uw volgende retry met dezelfde sleutel krijgt een nieuwe poging.

Header-echo

Geslaagde idempotente responses echoën de sleutel terug in de Idempotency-Key response-header — handig voor logging / correlatie.

Sleutels genereren

Gebruik iets dat globaal uniek is per logische operatie:

  • crypto.randomUUID() in Node 19+
  • uuid.uuid4() in Python
  • Uw business-process-id (bijv. claimnummer + tijdstempel) als u leesbare traces in logs wilt

SDK-helpers

// @nexbasira/node — pass via second arg
await nb.sessions.create(
  { notes: "..." },
  { idempotencyKey: crypto.randomUUID() },
);

// nexbasira (Python)
nb.sessions.create(notes="...", idempotency_key=str(uuid.uuid4()))

Wat nu