LIVE · AUDIT-KEDJA · EU-VÄRD
SYSTEM · 99,99 % DRIFTSTID
v 1.0 ↗ TILLVERKAT I EU

Paginering + idempotens

Cursor-paginering + Idempotency-Key-header för NexBasiras publika API.

Paginering + idempotens

Cursor-paginering på varje list-endpoint; Idempotency-Key på varje state-muterande endpoint. Två mönster att internalisera en gång; varje endpoint följer dem.

Cursor-paginering

Alla list-endpoints (GET /api/v1/public/sessions, /evidence, /whiteboards, m.fl.) returnerar en envelope: 

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

Hur du paginerar

  1. Gör det första anropet utan en cursor-param.
  2. Om has_more är true, skicka next_cursor ordagrant som cursor-query-param på nästa anrop.
  3. Upprepa tills has_more är 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

ParamStandardMax
limit25100

Högre limit-värden minskar antalet tur-och-retur-anrop men ökar payload-storleken per svar + serialiseringstiden. Standardvärdet 25 passar för UI-bruk; nattliga batch-jobb skickar vanligtvis 100.

Cursorns form

Cursorn är opak för klienter — det är en base64-kodad JSON-blob som kodar positionen i det underliggande queryset. Parsa eller konstruera inte cursors; skicka dem bara ordagrant. Formen är inte stabil mellan API-versioner.

Ordning

Standardordningen är created_at DESC (nyast först) för varje list-endpoint. Det är också den ordning cursorn går framåt i — du vandrar från senaste till äldsta när du paginerar.

SDK-hjälpare

Båda SDK:erna levererar en transparent async-iterator som paginerar åt dig:

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

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

Idempotens

Varje state-muterande endpoint accepterar en Idempotency-Key-header. Skicka en unik nyckel (vanligtvis en UUID) per logisk operation; ett omförsök med samma nyckel returnerar det cachade svaret utan att återskapa resursen. 

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-fönster

Cachade svar lever i 24 timmar. Ett replay efter 24h med samma nyckel skapar en ny resurs — behandla nyckeln som giltig endast under din retry-loop.

Scoping

Nycklar är scope:ade till (credential, endpoint, method):

  • Ett omförsök från samma credential till samma endpoint med samma nyckel returnerar det cachade svaret.
  • En annan credential som använder samma nyckel skapar en ny resurs (behandlas som ett nytt anrop).
  • Samma nyckel på en annan endpoint skapar en ny resurs (separat cache-slot).

Vad som cachas

Endast lyckade svar (2xx). Ett misslyckat anrop förgiftar inte cachen — ditt nästa omförsök med samma nyckel får ett nytt försök.

Header-eko

Lyckade idempotenta svar ekar tillbaka nyckeln i Idempotency-Key-svarsheadern — användbart för loggning / korrelation.

Generera nycklar

Använd vad som helst som är globalt unikt per logisk operation:

  • crypto.randomUUID() i Node 19+
  • uuid.uuid4() i Python
  • Ditt affärsprocess-id (t.ex. ärendenummer + tidsstämpel) om du vill ha människoläsbara spår i loggarna

SDK-hjälpare

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

Vad händer härnäst