Paginare + idempotență

Paginare prin cursor pe fiecare endpoint de listare; Idempotency-Key pe fiecare endpoint care modifică starea. Două tipare de internalizat o singură dată; fiecare endpoint le urmează.

Paginare prin cursor

Toate endpoint-urile de listare (GET /api/v1/public/sessions, /evidence, /whiteboards etc.) returnează un plic:

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

Cum se paginează

Emiteți prima cerere fără parametrul cursor.
Dacă has_more este true, transmiteți next_cursor verbatim ca parametru de query cursor la următoarea cerere.
Repetați până când has_more este 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_..."

Limite

Param	Implicit	Max
`limit`	25	100

Valori mai mari de limit reduc numărul de dus-întors, dar cresc dimensiunea payload-ului per răspuns + timpul de serializare. Valoarea implicită 25 este potrivită pentru utilizarea în UI; job-urile batch nocturne transmit de obicei 100.

Forma cursorului

Cursorul este opac pentru clienți — este un blob JSON codat base64 care codifică poziția în queryset-ul de bază. Nu parsați și nu construiți cursoare; doar transmiteți-le verbatim. Forma nu este stabilă între versiunile API.

Ordonare

Ordonarea implicită este created_at DESC (cele mai noi primele) pentru fiecare endpoint de listare. Aceasta este și ordinea în care avansează cursorul — veți parcurge de la cel mai recent la cel mai vechi pe măsură ce paginați.

Funcții ajutătoare SDK

Ambele SDK-uri livrează un async-iterator transparent care paginează în locul dvs.:

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

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

Idempotență

Fiecare endpoint care modifică starea acceptă un antet Idempotency-Key. Transmiteți o cheie unică (de obicei un UUID) per operație logică; o reîncercare cu aceeași cheie returnează răspunsul din cache fără a re-crea resursa.

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

Fereastra de cache

Răspunsurile din cache trăiesc 24 de ore. Reluarea după 24h cu aceeași cheie creează o resursă nouă — tratați cheia ca validă doar pe durata buclei dvs. de reîncercare.

Restrângere (scoping)

Cheile sunt restrânse la (credential, endpoint, method):

O reîncercare de la aceeași credențială către același endpoint cu aceeași cheie returnează răspunsul din cache.
O credențială diferită care folosește aceeași cheie creează o resursă nouă (o tratează ca pe un apel nou).
Aceeași cheie pe un endpoint diferit creează o resursă nouă (slot de cache separat).

Ce se pune în cache

Doar răspunsurile de succes (2xx). O cerere eșuată nu otrăvește cache-ul — următoarea dvs. reîncercare cu aceeași cheie primește o încercare nouă.

Ecou de antet

Răspunsurile idempotente de succes returnează cheia în antetul de răspuns Idempotency-Key — util pentru logging / corelare.

Generarea cheilor

Folosiți orice este global unic per operație logică:

crypto.randomUUID() în Node 19+
uuid.uuid4() în Python
Id-ul procesului dvs. de business (de ex. număr de dosar + marcaj temporal) dacă doriți urme lizibile de om în log-uri

Funcții ajutătoare SDK

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

Ce urmează

Erori + rate limits — ce se întâmplă când paginarea sau buclele de reîncercare merg prost
API Sessions — primul endpoint la care se aplică ambele tipare