Sivutus + idempotenssi

Kursorisivutus jokaisessa listauspäätepisteessä; Idempotency-Key jokaisessa tilaa muuttavassa päätepisteessä. Kaksi kuviota sisäistettäväksi kerran; jokainen päätepiste noudattaa niitä.

Kursorisivutus

Kaikki listauspäätepisteet (GET /api/v1/public/sessions, /evidence, /whiteboards jne.) palauttavat kuoren:

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

Miten sivuttaa

Tee ensimmäinen pyyntö ilman cursor-parametria.
Jos has_more on true, välitä next_cursor sellaisenaan cursor-kyselyparametrina seuraavassa pyynnössä.
Toista, kunnes has_more on 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_..."

Rajat

Parametri	Oletus	Maksimi
`limit`	25	100

Korkeammat limit-arvot vähentävät edestakaisten pyyntöjen määrää mutta lisäävät vastauskohtaista hyötykuorman kokoa + serialisointiaikaa. Oletus 25 sopii käyttöliittymäkäyttöön; öiset erätyöt välittävät tyypillisesti 100.

Kursorin muoto

Kursori on läpinäkymätön asiakkaille — se on base64-koodattu JSON-blob, joka koodaa sijainnin taustalla olevassa querysetissä. Älä jäsennä tai muodosta kursoreita; välitä ne vain sellaisenaan. Muoto ei ole vakaa API-versioiden yli.

Järjestys

Oletusjärjestys on created_at DESC (uusin ensin) jokaisessa listauspäätepisteessä. Tämä on myös järjestys, jossa kursori etenee — kävelet uusimmasta vanhimpaan sivuttaessasi.

SDK-apurit

Molemmat SDK:t toimittavat läpinäkyvän async-iteraattorin, joka sivuttaa puolestasi:

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

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

Idempotenssi

Jokainen tilaa muuttava päätepiste hyväksyy Idempotency-Key-otsakkeen. Välitä yksilöivä avain (tyypillisesti UUID) per looginen operaatio; uudelleenyritys samalla avaimella palauttaa välimuistitetun vastauksen luomatta resurssia uudelleen.

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"}'

Välimuisti-ikkuna

Välimuistitetut vastaukset elävät 24 tuntia. Toisto 24 tunnin jälkeen samalla avaimella luo uuden resurssin — käsittele avainta voimassaolevana vain uudelleenyrityssilmukkasi ajan.

Rajaus

Avaimet rajataan (credential, endpoint, method):iin:

Uudelleenyritys samasta tunnisteesta samaan päätepisteeseen samalla avaimella palauttaa välimuistitetun vastauksen.
Eri tunniste samalla avaimella luo uuden resurssin (kohtelee sitä tuoreena kutsuna).
Sama avain eri päätepisteessä luo uuden resurssin (erillinen välimuistipaikka).

Mitä välimuistitetaan

Vain onnistuneet vastaukset (2xx). Epäonnistunut pyyntö ei myrkytä välimuistia — seuraava uudelleenyrityksesi samalla avaimella saa tuoreen yrityksen.

Otsakkeen kaiku

Onnistuneet idempotentit vastaukset kaiuttavat avaimen takaisin Idempotency-Key-vastausotsakkeessa — hyödyllinen lokitukseen / korrelaatioon.

Avainten generointi

Käytä mitä tahansa, joka on globaalisti yksilöivä per looginen operaatio:

crypto.randomUUID() Node 19+:ssa
uuid.uuid4() Pythonissa
Liiketoimintaprosessisi id (esim. korvausnumero + aikaleima), jos haluat ihmisluettavia jälkiä lokeihin

SDK-apurit

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

Mitä seuraavaksi

Virheet + nopeusrajat — mitä tapahtuu kun sivutus tai uudelleenyrityssilmukat menevät vikaan
Sessions API — ensimmäinen päätepiste, jossa soveltaa molempia kuvioita