Paginering + idempotens

Cursor-paginering på hvert list-endpoint; Idempotency-Key på hvert tilstandsmuterende endpoint. To mønstre at internalisere én gang; hvert endpoint følger dem.

Cursor-paginering

Alle list-endpoints (GET /api/v1/public/sessions, /evidence, /whiteboards, osv.) returnerer en konvolut:

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

Sådan paginerer du

Udsted den første anmodning uden en cursor-parameter.
Hvis has_more er true, skal du sende next_cursor ordret som cursor-query-parameteren på den næste anmodning.
Gentag, indtil has_more er false.

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_..."

Grænser

Parameter	Standard	Maks
`limit`	25	100

Højere limit-værdier reducerer antallet af rundture, men øger payload-størrelsen pr. svar + serialiseringstiden. Standarden 25 er velegnet til UI-brug; natlige batch-jobs sender typisk 100.

Cursor-form

Cursoren er uigennemsigtig for klienter — det er en base64-kodet JSON-blob, der koder positionen i det underliggende queryset. Parse eller konstruer ikke cursors; send dem bare ordret. Formen er ikke stabil på tværs af API-versioner.

Rækkefølge

Standardrækkefølgen er created_at DESC (nyeste først) for hvert list-endpoint. Dette er også den rækkefølge, cursoren rykker frem i — du vandrer fra nyeste til ældste, mens du paginerer.

SDK-hjælpere

Begge SDK'er leveres med en gennemsigtig async-iterator, der paginerer for dig:

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

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

Idempotens

Hvert tilstandsmuterende endpoint accepterer en Idempotency-Key-header. Send en unik nøgle (typisk en UUID) pr. logisk operation; et gentaget forsøg med den samme nøgle returnerer det cachede svar uden at genskabe ressourcen.

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-vindue

Cachede svar lever i 24 timer. Genafspilning efter 24 timer med den samme nøgle opretter en ny ressource — behandl nøglen som gyldig kun i den periode, dit genforsøgs-loop varer.

Scoping

Nøgler er scoped til (credential, endpoint, method):

Et genforsøg fra samme legitimation til samme endpoint med samme nøgle returnerer det cachede svar.
En anden legitimation, der bruger samme nøgle, opretter en ny ressource (behandler det som et nyt kald).
Samme nøgle på et andet endpoint opretter en ny ressource (separat cache-slot).

Hvad der bliver cachet

Kun vellykkede svar (2xx). En mislykket anmodning forgifter ikke cachen — dit næste genforsøg med samme nøgle får et nyt forsøg.

Header-ekko

Vellykkede idempotente svar ekkoer nøglen tilbage i Idempotency-Key-svarheaderen — nyttigt til logning / korrelation.

Generering af nøgler

Brug hvad som helst, der er globalt unikt pr. logisk operation:

crypto.randomUUID() i Node 19+
uuid.uuid4() i Python
Dit forretningsproces-id (f.eks. skadesnummer + tidsstempel), hvis du vil have menneskelæsbare spor i logfiler

SDK-hjælpere

// @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()))

Hvad er det næste

Fejl + rate limits — hvad der sker, når paginering eller genforsøgs-loops går galt
Sessions-API — første endpoint til at anvende begge mønstre