ΖΩΝΤΑΝΑ · ΑΛΥΣΙΔΑ ΕΛΕΓΧΟΥ · ΕΕ
ΣΥΣΤΗΜΑ · 99,99% ΔΙΑΘΕΣΙΜΟΤΗΤΑ
v 1.0 ↗ ΦΤΙΑΓΜΕΝΟ ΣΤΗΝ ΕΕ

Σελιδοποίηση + idempotency

Σελιδοποίηση με cursor + κεφαλίδα Idempotency-Key για το δημόσιο API του NexBasira.

Σελιδοποίηση + idempotency

Σελιδοποίηση με cursor σε κάθε endpoint λίστας· Idempotency-Key σε κάθε endpoint που μεταβάλλει κατάσταση. Δύο μοτίβα που εσωτερικεύετε μία φορά· κάθε endpoint τα ακολουθεί.

Σελιδοποίηση με cursor

Όλα τα endpoints λίστας (GET /api/v1/public/sessions, /evidence, /whiteboards κ.λπ.) επιστρέφουν έναν φάκελο: 

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

Πώς να σελιδοποιήσετε

  1. Στείλτε το πρώτο αίτημα χωρίς παράμετρο cursor.
  2. Αν το has_more είναι true, περάστε το next_cursor αυτούσιο ως query param cursor στο επόμενο αίτημα.
  3. Επαναλάβετε μέχρι το 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_..."

Όρια

ParamΠροεπιλογήΜέγιστο
limit25100

Υψηλότερες τιμές limit μειώνουν τον αριθμό round-trip αλλά αυξάνουν το μέγεθος του payload ανά απόκριση + τον χρόνο serialisation. Η προεπιλογή 25 είναι κατάλληλη για χρήση UI· οι νυχτερινές batch εργασίες συνήθως περνούν 100.

Μορφή cursor

Το cursor είναι αδιαφανές για τους clients — είναι ένα JSON blob κωδικοποιημένο σε base64 που κωδικοποιεί τη θέση στο υποκείμενο queryset. Μην αναλύετε ή κατασκευάζετε cursors· απλώς περνάτε τα αυτούσια. Η μορφή δεν είναι σταθερή μεταξύ εκδόσεων API.

Ταξινόμηση

Η προεπιλεγμένη ταξινόμηση είναι created_at DESC (νεότερα πρώτα) για κάθε endpoint λίστας. Αυτή είναι επίσης η σειρά με την οποία προχωρά το cursor — θα κινηθείτε από το πιο πρόσφατο προς το παλαιότερο καθώς σελιδοποιείτε.

Βοηθητικές συναρτήσεις SDK

Και τα δύο SDK διαθέτουν έναν διαφανή async-iterator που σελιδοποιεί για εσάς:

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

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

Idempotency

Κάθε endpoint που μεταβάλλει κατάσταση δέχεται μια κεφαλίδα Idempotency-Key. Περάστε ένα μοναδικό κλειδί (συνήθως ένα UUID) ανά λογική λειτουργία· μια επανάληψη με το ίδιο κλειδί επιστρέφει την cached απόκριση χωρίς να αναδημιουργεί τον πόρο. 

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

Οι cached αποκρίσεις ζουν για 24 ώρες. Επανάληψη μετά τις 24 ώρες με το ίδιο κλειδί δημιουργεί νέο πόρο — αντιμετωπίστε το κλειδί ως έγκυρο μόνο για τη διάρκεια του βρόχου επανάληψής σας.

Scoping

Τα κλειδιά περιορίζονται σε (credential, endpoint, method):

  • Μια επανάληψη από το ίδιο διαπιστευτήριο προς το ίδιο endpoint με το ίδιο κλειδί επιστρέφει την cached απόκριση.
  • Ένα διαφορετικό διαπιστευτήριο που χρησιμοποιεί το ίδιο κλειδί δημιουργεί νέο πόρο (το αντιμετωπίζει ως νέα κλήση).
  • Το ίδιο κλειδί σε διαφορετικό endpoint δημιουργεί νέο πόρο (ξεχωριστή θέση cache).

Τι αποθηκεύεται στην cache

Μόνο επιτυχείς αποκρίσεις (2xx). Ένα αποτυχημένο αίτημα δεν δηλητηριάζει την cache — η επόμενη επανάληψή σας με το ίδιο κλειδί παίρνει μια νέα προσπάθεια.

Επανάληψη κεφαλίδας

Οι επιτυχείς idempotent αποκρίσεις επαναλαμβάνουν το κλειδί στην κεφαλίδα απόκρισης Idempotency-Key — χρήσιμο για logging / συσχέτιση.

Δημιουργία κλειδιών

Χρησιμοποιήστε οτιδήποτε είναι καθολικά μοναδικό ανά λογική λειτουργία:

  • crypto.randomUUID() στο Node 19+
  • uuid.uuid4() στην Python
  • Το id της επιχειρησιακής σας διαδικασίας (π.χ. αριθμός απαίτησης + χρονοσφραγίδα) αν θέλετε ευανάγνωστα ίχνη στα logs

Βοηθητικές συναρτήσεις 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()))

Τι ακολουθεί