Lehitsemine

Sursa API loendeid lehitsetakse kursoriga: te küsite kuni limit elementi ja vastus ütleb, kuidas saada järgmine leht. Te ei pea kunagi nihkeid arvutama ning elemendid ei kordu ega kao lehtede vahel, kui andmed vahepeal muutuvad.

Loend tagastab järgmise kursori ühel kahest viisist, olenevalt vastuse kujust. API teatmikus näitab iga lõpp-punkti leht, kumba viisi see kasutab.

Loendid, mis kasutavad data-ümbrist

Avaliku API jaoks lisatud loendid, näiteks sündmuste lint, tagastavad objekti, mille elemendid on väljal 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
}

Kui has_more on true, küsige järgmist lehte nii, et parameetri cursor väärtus on next_cursor ja filtrid on samad:

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

Loendid, mis olid olemas enne kursoreid ja tagastavad objekti, säilitavad oma ümbrise (näiteks {"items": […], "total": 120}). Need saavad samasse objekti väljad next_cursor ja has_more; elemendid jäävad oma kohale.

Massiivi tagastavad loendid

Mõni loend tagastab palja JSON-massiivi, näiteks GET /v1/collections. Nende vastuse kuju ei saa muutuda, seega tuleb järgmine leht hoopis päistes:

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", …}, …]

• Päis Link väärtusega rel="next" on järgmise lehe täielik aadress; X-Next-Cursor on sama kursor eraldi.
• Kui päist Link väärtusega rel="next" ja päist X-Next-Cursor ei ole, on see viimane leht.
• Ilma parameetrita limit tagastavad need loendid kõik elemendid ühes vastuses, nagu alati. Lehitsemiseks edastage limit; kursor jätab lehe suuruse meelde, seega võib järgmine päring parameetri limit ära jätta.
• GET /v1/cards on erand: see tagastab alati lehti, vaikimisi 200 kaarti ja parameetriga limit kuni 1000, seega järgige päist X-Next-Cursor ka ilma parameetrita 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;
  }
}

Sündmuste lint

Sündmuste lint GET /v1/webhook-events on logi, seega lehitsetakse seda veidi teisiti:

• Sündmused on kasvavas järjekorras, vanim esimesena.
• next_cursor tagastatakse igal lehel, isegi kui has_more on false. Salvestage see ja küsige hiljem sama kursoriga uuesti, et saada vahepeal toimunud sündmused. Lint on järjekord, mida saate lugeda omas tempos.
• Sündmus ilmub linti umbes sekundi jooksul pärast muudatust, mida see kirjeldab, ja mitte kunagi enne juba loetud sündmust.
• Lint sisaldab kogu organisatsiooni sündmusi, seega on selle lugemiseks vaja võtit, millel on roll admin ja ulatus webhooks:manage.

Eksport andmelattu näitab täielikku küsitlustsüklit.

Kursorite reeglid

• Kursor on kuni 512 märgi pikkune läbipaistmatu string. Ärge seda parsige ega koostage ise: selle vorming võib muutuda.
• Kursor kuulub ühele loendile ja ühele filtrite komplektile. Kursor, mis on rikutud, pärineb teisest loendist või saadetakse teiste filtritega, tagastab 400 koodiga api.cursor_invalid.
• Igal loendil on kindel sortimisjärjekord, mis lõpeb unikaalse võtmega, seega on iga element täpselt ühel lehel.
• Kursoritega lisatud loendid ei tagasta koguarvu; loendid, millel oli varem väli total, säilitavad selle. Kui vajate koguarvu, loendage elemente lehitsemise käigus.

Nihkepõhine (offset) lehitsemine

Mõned loendid võtsid enne kursorite kasutuselevõttu vastu parameetri offset ja teevad seda endiselt, et olemasolevad integratsioonid töötaksid edasi. Eelistage uues koodis parameetrit cursor. Parameetreid offset ja cursor ei saa kombineerida: mõlema saatmine tagastab 422 koodiga validation.failed.