ŽIVĚ · AUDIT CHAIN · EU
SYSTÉM · 99,99 % DOSTUPNOST
v 1.0 ↗ VYROBENO V EU

Stránkování + idempotence

Kurzorové stránkování + hlavička Idempotency-Key pro veřejné API NexBasira.

Stránkování + idempotence

Kurzorové stránkování na každém endpointu pro výpis; Idempotency-Key na každém endpointu měnícím stav. Dva vzory, které si jednou osvojíte; každý endpoint je dodržuje.

Kurzorové stránkování

Všechny endpointy pro výpis (GET /api/v1/public/sessions, /evidence, /whiteboards atd.) vracejí obálku: 

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

Jak stránkovat

  1. Odešlete první požadavek bez parametru cursor.
  2. Pokud je has_more true, předejte next_cursor doslovně jako query parametr cursor v dalším požadavku.
  3. Opakujte, dokud není has_more 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_..."

Limity

ParametrVýchozíMax
limit25100

Vyšší hodnoty limit snižují počet round-tripů, ale zvyšují velikost payloadu na odpověď + čas serializace. Výchozí hodnota 25 je vhodná pro použití v UI; noční dávkové úlohy typicky předávají 100.

Tvar kurzoru

Kurzor je pro klienty neprůhledný — je to JSON blob zakódovaný v base64, který kóduje pozici v podkladovém querysetu. Nerozebírejte ani nekonstruujte kurzory; jen je předávejte doslovně. Tvar není stabilní napříč verzemi API.

Řazení

Výchozí řazení je created_at DESC (nejnovější první) pro každý endpoint pro výpis. To je také pořadí, ve kterém kurzor postupuje — při stránkování budete procházet od nejnovějšího k nejstaršímu.

Pomocníci SDK

Obě SDK dodávají transparentní async iterátor, který za vás stránkuje:

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

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

Idempotence

Každý endpoint měnící stav přijímá hlavičku Idempotency-Key. Předejte jedinečný klíč (typicky UUID) na logickou operaci; opakování se stejným klíčem vrátí odpověď z mezipaměti bez opětovného vytvoření zdroje. 

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

Okno mezipaměti

Odpovědi v mezipaměti žijí 24 hodin. Přehrání po 24 h se stejným klíčem vytvoří nový zdroj — považujte klíč za platný pouze po dobu vaší smyčky opakování.

Rozsah

Klíče jsou omezeny na (credential, endpoint, method):

  • Opakování ze stejných přihlašovacích údajů na stejný endpoint se stejným klíčem vrátí odpověď z mezipaměti.
  • Jiné přihlašovací údaje používající stejný klíč vytvoří nový zdroj (zachází s ním jako s novým voláním).
  • Stejný klíč na jiném endpointu vytvoří nový zdroj (samostatný slot mezipaměti).

Co se ukládá do mezipaměti

Pouze úspěšné odpovědi (2xx). Neúspěšný požadavek mezipaměť neotráví — vaše další opakování se stejným klíčem dostane nový pokus.

Odezva hlavičky

Úspěšné idempotentní odpovědi vracejí klíč zpět v odpovědní hlavičce Idempotency-Key — užitečné pro logování / korelaci.

Generování klíčů

Použijte cokoli, co je globálně jedinečné pro každou logickou operaci:

  • crypto.randomUUID() v Node 19+
  • uuid.uuid4() v Pythonu
  • ID vašeho obchodního procesu (např. číslo pojistné události + časové razítko), pokud chcete v logech čitelné stopy

Pomocníci 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()))

Co dál