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

Οι λίστες του API της Sursa σελιδοποιούνται με δρομέα (cursor): ζητάτε έως limit στοιχεία και η απόκριση σας λέει πώς να πάρετε την επόμενη σελίδα. Δεν υπολογίζετε ποτέ μετατοπίσεις, και τα στοιχεία δεν επαναλαμβάνονται ούτε χάνονται μεταξύ των σελίδων όταν τα δεδομένα αλλάζουν στο μεταξύ.

Μια λίστα επιστρέφει τον επόμενο δρομέα με έναν από δύο τρόπους, ανάλογα με τη μορφή της απόκρισής της. Η σελίδα κάθε τελικού σημείου στην αναφορά API δείχνει ποιον χρησιμοποιεί.

Λίστες με περίβλημα data

Οι λίστες που προστέθηκαν για το δημόσιο API, όπως η τροφοδοσία συμβάντων, επιστρέφουν ένα αντικείμενο με τα στοιχεία στο data:

curl "https://api.sursa.com/v1/webhook-events?limit=2" \
  -H "Authorization: Bearer $SURSA_API_KEY"

{
  "data": [
    {"id": "evt_8a1f…", "type": "card.published", "created_at": "2026-10-24T10:00:00Z"},
    {"id": "evt_8a20…", "type": "card.updated", "created_at": "2026-10-24T10:00:03Z"}
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbMTA0Ml19",
  "has_more": true
}

Όταν το has_more είναι true, ζητήστε την επόμενη σελίδα με το cursor ίσο με το next_cursor και τα ίδια φίλτρα:

curl "https://api.sursa.com/v1/webhook-events?limit=2&cursor=eyJ2IjoxLCJrIjpbMTA0Ml19" \
  -H "Authorization: Bearer $SURSA_API_KEY"

Οι λίστες που υπήρχαν πριν από τους δρομείς και επιστρέφουν ένα αντικείμενο διατηρούν το δικό τους περίβλημα (για παράδειγμα {"items": […], "total": 120}). Παίρνουν next_cursor και has_more στο ίδιο αντικείμενο· τα στοιχεία μένουν εκεί που ήταν.

Λίστες που επιστρέφουν πίνακα

Λίγες λίστες επιστρέφουν σκέτο πίνακα JSON, για παράδειγμα το GET /v1/collections. Η μορφή της απόκρισής τους δεν μπορεί να αλλάξει, γι’ αυτό η επόμενη σελίδα έρχεται στις κεφαλίδες:

curl -i "https://api.sursa.com/v1/collections?limit=50" \
  -H "Authorization: Bearer $SURSA_API_KEY"

HTTP/1.1 200 OK
Link: <https://api.example.com/v1/collections?limit=50&cursor=eyJ2IjoxLCJrIjpbNTBdfQ>; rel="next"
X-Next-Cursor: eyJ2IjoxLCJrIjpbNTBdfQ

[{"id": 1, "name": "support", …}, …]

• Το Link με rel="next" είναι η πλήρης διεύθυνση της επόμενης σελίδας· το X-Next-Cursor είναι ο ίδιος δρομέας μόνος του.
• Αν δεν υπάρχει Link με rel="next" ούτε X-Next-Cursor, αυτή είναι η τελευταία σελίδα.
• Χωρίς limit, αυτές οι λίστες επιστρέφουν όλα τα στοιχεία σε μία απόκριση, όπως πάντα. Περάστε limit για να τις σελιδοποιήσετε· ο δρομέας θυμάται το μέγεθος σελίδας, οπότε το επόμενο αίτημα μπορεί να παραλείψει το limit.
• Το GET /v1/cards αποτελεί εξαίρεση: επιστρέφει πάντα σελίδες, 200 κάρτες από προεπιλογή και έως 1000 με limit, οπότε ακολουθήστε το X-Next-Cursor ακόμη και χωρίς limit.

// Every item of a list that returns an array.
async function* listArray(path) {
  let next = `https://api.sursa.com${path}?limit=200`;
  while (next) {
    const response = await fetch(next, { headers: { Authorization: `Bearer ${process.env.SURSA_API_KEY}` } });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    yield* await response.json();
    const cursor = response.headers.get("X-Next-Cursor");
    next = cursor ? `https://api.sursa.com${path}?cursor=${encodeURIComponent(cursor)}` : null;
  }
}

Η τροφοδοσία συμβάντων

Η τροφοδοσία συμβάντων GET /v1/webhook-events είναι ένα αρχείο καταγραφής, γι’ αυτό σελιδοποιείται λίγο διαφορετικά:

• Τα συμβάντα είναι σε αύξουσα σειρά, τα παλαιότερα πρώτα.
• Το next_cursor επιστρέφεται σε κάθε σελίδα, ακόμη και όταν το has_more είναι false. Αποθηκεύστε το και ρωτήστε ξανά αργότερα με τον ίδιο δρομέα, για να λάβετε τα συμβάντα που συνέβησαν στο μεταξύ. Η τροφοδοσία είναι μια ουρά που διαβάζετε με τον δικό σας ρυθμό.
• Ένα συμβάν εμφανίζεται στην τροφοδοσία περίπου ένα δευτερόλεπτο μετά την αλλαγή που περιγράφει και ποτέ πριν από ένα συμβάν που έχει ήδη διαβαστεί.
• Η τροφοδοσία περιέχει τα συμβάντα ολόκληρου του οργανισμού, γι’ αυτό για να τη διαβάσετε χρειάζεστε ένα κλειδί με τον ρόλο admin και την εμβέλεια webhooks:manage.

Ο οδηγός Εξαγωγή σε αποθήκη δεδομένων δείχνει έναν πλήρη βρόχο περιοδικού ελέγχου.

Κανόνες για τους δρομείς

• Ένας δρομέας είναι μια αδιαφανής συμβολοσειρά έως 512 χαρακτήρων. Μην τον αναλύετε και μην τον κατασκευάζετε μόνοι σας: η μορφή του μπορεί να αλλάξει.
• Ένας δρομέας ανήκει σε μία λίστα και σε ένα σύνολο φίλτρων. Ένας δρομέας που είναι κατεστραμμένος, προέρχεται από άλλη λίστα ή στέλνεται με διαφορετικά φίλτρα επιστρέφει 400 με τον κωδικό api.cursor_invalid.
• Κάθε λίστα έχει σταθερή σειρά ταξινόμησης που τελειώνει σε ένα μοναδικό κλειδί, ώστε κάθε στοιχείο να εμφανίζεται σε ακριβώς μία σελίδα.
• Οι λίστες που προστέθηκαν με δρομείς δεν επιστρέφουν συνολικό πλήθος· οι λίστες που είχαν ήδη total το διατηρούν. Μετράτε τα στοιχεία στην πορεία, αν χρειάζεστε σύνολο.

Σελιδοποίηση με μετατόπιση

Ορισμένες λίστες δέχονταν offset πριν εισαχθούν οι δρομείς και εξακολουθούν να το δέχονται, ώστε να συνεχίσουν να λειτουργούν οι υπάρχουσες ενσωματώσεις. Στον νέο κώδικα προτιμήστε το cursor. Τα offset και cursor δεν συνδυάζονται: αν στείλετε και τα δύο, επιστρέφεται 422 με τον κωδικό validation.failed.