LIVE · AUDIT-KJEDE · EU-VERTET
SYSTEM · 99,99 % OPPETID
v 1.0 ↗ LAGET I EU

Paginering + idempotens

Cursor-paginering + Idempotency-Key-header for NexBasira sin offentlige API.

Paginering + idempotens

Cursor-paginering på hvert liste-endepunkt; Idempotency-Key på hvert tilstandsendrende endepunkt. To mønstre å internalisere én gang; hvert endepunkt følger dem.

Cursor-paginering

Alle liste-endepunkter (GET /api/v1/public/sessions, /evidence, /whiteboards, osv.) returnerer en konvolutt: 

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

Slik paginerer du

  1. Send den første forespørselen uten en cursor-parameter.
  2. Hvis has_more er true, send next_cursor ordrett som cursor-spørringsparameter på neste forespørsel.
  3. Gjenta til 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_..."

Grenser

ParameterStandardMaks
limit25100

Høyere limit-verdier reduserer antall rundturer, men øker payload-størrelsen per respons + serialiseringstiden. Standard 25 passer for UI-bruk; nattlige batchjobber sender typisk 100.

Cursor-form

Cursoren er ugjennomsiktig for klienter — den er en base64-kodet JSON-blob som koder posisjonen i det underliggende queryset-et. Ikke parse eller konstruer cursors; bare send dem ordrett. Formen er ikke stabil på tvers av API-versjoner.

Rekkefølge

Standard rekkefølge er created_at DESC (nyeste først) for hvert liste-endepunkt. Dette er også rekkefølgen cursoren beveger seg i — du vil gå fra nyeste til eldste etter hvert som du paginerer.

SDK-hjelpere

Begge SDK-ene leverer en transparent async-iterator som paginerer for deg:

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

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

Idempotens

Hvert tilstandsendrende endepunkt godtar en Idempotency-Key-header. Send en unik nøkkel (typisk en UUID) per logiske operasjon; et nytt forsøk med samme nøkkel returnerer den cachede responsen uten å opprette ressursen på nytt. 

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

Cachede responser lever i 24 timer. Å spille av på nytt etter 24t med samme nøkkel oppretter en ny ressurs — behandle nøkkelen som gyldig bare for varigheten av retry-loopen din.

Scope-avgrensning

Nøkler er avgrenset til (credential, endpoint, method):

  • Et nytt forsøk fra samme legitimasjon til samme endepunkt med samme nøkkel returnerer den cachede responsen.
  • En annen legitimasjon som bruker samme nøkkel oppretter en ny ressurs (behandler det som et nytt kall).
  • Samme nøkkel på et annet endepunkt oppretter en ny ressurs (egen cache-plass).

Hva som caches

Bare vellykkede responser (2xx). En mislykket forespørsel forgifter ikke cachen — det neste forsøket ditt med samme nøkkel får et nytt forsøk.

Header-ekko

Vellykkede idempotente svar sender nøkkelen tilbake i Idempotency-Key-svarhodet — nyttig for logging / korrelasjon.

Generere nøkler

Bruk hva som helst som er globalt unikt per logisk operasjon:

  • crypto.randomUUID() i Node 19+
  • uuid.uuid4() i Python
  • Din forretningsprosess-id (f.eks. skadenummer + tidsstempel) hvis du vil ha lesbare spor i loggene

SDK-hjelpere

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

Hva er neste steg