Puslapiavimas

Sursa API sąrašai skaidomi puslapiais naudojant žymeklį: prašote ne daugiau kaip limit elementų, o atsakas nurodo, kaip gauti kitą puslapį. Poslinkių niekada neskaičiuojate, o elementai tarp puslapių nesikartoja ir nedingsta, net jei tuo metu duomenys keičiasi.

Sąrašas kitą žymeklį grąžina vienu iš dviejų būdų, priklausomai nuo atsako formos. Kiekvienos operacijos puslapyje API žinyne nurodyta, kurį būdą ji naudoja.

Sąrašai su duomenų voku

Viešajai API pridėti sąrašai, pavyzdžiui, įvykių juosta, grąžina objektą, kurio elementai yra lauke 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
}

Kai has_more yra true, kito puslapio prašykite su cursor, lygiu next_cursor, ir tais pačiais filtrais:

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

Sąrašai, egzistavę dar iki žymeklių ir grąžinantys objektą, išlaiko savo voką (pavyzdžiui, {"items": […], "total": 120}). Jie gauna next_cursor ir has_more tame pačiame objekte; elementai lieka ten, kur buvo.

Sąrašai, grąžinantys masyvą

Keli sąrašai grąžina paprastą JSON masyvą, pavyzdžiui, GET /v1/collections. Jų atsako forma pasikeisti negali, todėl kitas puslapis nurodomas antraštėse:

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 su rel="next" – visas kito puslapio adresas; X-Next-Cursor – tas pats žymeklis atskirai.
• Jei nėra nei Link su rel="next", nei X-Next-Cursor, tai paskutinis puslapis.
• Be limit šie sąrašai, kaip ir visada, grąžina visus elementus viename atsake. Perduokite limit, kad juos skaidytumėte puslapiais; žymeklis įsimena puslapio dydį, todėl kitoje užklausoje limit galima nenurodyti.
• GET /v1/cards yra išimtis: jis visada grąžina puslapius, numatytai po 200 kortelių, o su limit – iki 1000, todėl X-Next-Cursor sekite net ir be 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;
  }
}

Įvykių juosta

Įvykių juosta GET /v1/webhook-events yra žurnalas, todėl puslapiais skaidoma šiek tiek kitaip:

• Įvykiai pateikiami didėjančia tvarka, seniausi – pirmi.
• next_cursor grąžinamas kiekviename puslapyje, net kai has_more yra false. Išsaugokite jį ir vėliau paklauskite su tuo pačiu žymekliu – gausite nuo to laiko įvykusius įvykius. Juosta – tai eilė, kurią galite skaityti savo tempu.
• Įvykis juostoje atsiranda maždaug per sekundę po jo aprašomo pakeitimo ir niekada ne anksčiau už jau perskaitytą įvykį.
• Juostoje yra visos organizacijos įvykiai, todėl jai skaityti reikia rakto su vaidmeniu admin ir apimtimi webhooks:manage.

Eksportas į duomenų sandėlį parodo visą apklausos ciklą.

Žymeklių taisyklės

• Žymeklis – nepermatoma iki 512 simbolių eilutė. Jo neanalizuokite ir nesudarinėkite savo kode: jo formatas gali keistis.
• Žymeklis priklauso vienam sąrašui ir vienam filtrų rinkiniui. Sugadintas, iš kito sąrašo gautas ar su kitais filtrais išsiųstas žymeklis grąžina 400 su kodu api.cursor_invalid.
• Kiekvienas sąrašas turi fiksuotą rikiavimo tvarką, kuri baigiasi unikaliu raktu, todėl kiekvienas elementas pasirodo lygiai viename puslapyje.
• Su žymekliais pridėti sąrašai bendro skaičiaus negrąžina; sąrašai, kurie anksčiau turėjo total, jį išlaiko. Jei reikia bendro skaičiaus, elementus skaičiuokite puslapis po puslapio.

Puslapiavimas su poslinkiu

Kai kurie sąrašai offset priėmė dar prieš atsirandant žymekliams ir tebepriima, kad esamos integracijos veiktų toliau. Naujame kode rinkitės cursor. offset ir cursor derinti negalima: siunčiant abu, grąžinama 422 su kodu validation.failed.