Sivutus

Sursa API:n listat sivutetaan kursorilla: pyydät enintään limit kohdetta, ja vastaus kertoo, miten saat seuraavan sivun. Siirtymiä ei koskaan tarvitse laskea, eivätkä kohteet toistu tai katoa sivujen välillä, vaikka tiedot muuttuisivat sillä välin.

Lista palauttaa seuraavan kursorinsa jommallakummalla kahdesta tavasta vastauksensa rakenteen mukaan. API-viitteen kunkin päätepisteen sivu näyttää, kumpaa tapaa se käyttää.

Listat data-kääreellä

Julkista API:a varten lisätyt listat, kuten tapahtumasyöte, palauttavat objektin, jonka data-kentässä ovat kohteet:

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
}

Kun has_more on true, pyydä seuraava sivu niin, että cursor saa arvon next_cursor ja suodattimet ovat samat:

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

Listat, jotka olivat olemassa ennen kursoreita ja palauttavat objektin, säilyttävät oman kääreensä (esimerkiksi {"items": […], "total": 120}). Ne saavat next_cursor- ja has_more-kentät samaan objektiin; kohteet pysyvät paikoillaan.

Listat, jotka palauttavat taulukon

Muutama lista palauttaa pelkän JSON-taulukon, esimerkiksi GET /v1/collections. Niiden vastauksen rakenne ei voi muuttua, joten seuraava sivu tulee sen sijaan otsakkeissa:

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, jossa on rel="next", on seuraavan sivun koko osoite; X-Next-Cursor on sama kursori yksinään.
• Jos vastauksessa ei ole Link-otsaketta, jossa on rel="next", eikä X-Next-Cursor-otsaketta, sivu on viimeinen.
• Ilman limit-parametria nämä listat palauttavat kaikki kohteet yhdessä vastauksessa, kuten aina ennenkin. Anna limit, jos haluat sivuttaa ne; kursori muistaa sivukoon, joten seuraavasta pyynnöstä voi jättää limit-parametrin pois.
• GET /v1/cards on poikkeus: se palauttaa aina sivuja, oletuksena 200 korttia ja limit-parametrilla enintään 1000, joten seuraa X-Next-Cursor-otsaketta myös ilman limit-parametria.

// 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;
  }
}

Tapahtumasyöte

Tapahtumasyöte GET /v1/webhook-events on loki, joten se sivutetaan hieman eri tavalla:

• Tapahtumat ovat nousevassa järjestyksessä, vanhin ensin.
• next_cursor palautetaan jokaisella sivulla, myös silloin, kun has_more on false. Tallenna se ja kysy myöhemmin uudelleen samalla kursorilla, niin saat sillä välin tapahtuneet tapahtumat. Syöte on jono, jota voit lukea omaan tahtiisi.
• Tapahtuma ilmestyy syötteeseen noin sekunnin kuluessa muutoksesta, jota se kuvaa, eikä koskaan ennen jo luettua tapahtumaa.
• Syötteessä ovat koko organisaation tapahtumat, joten sen lukemiseen tarvitaan avain, jolla on rooli admin ja käyttöalue webhooks:manage.

Vienti tietovarastoon näyttää kokonaisen kyselysilmukan.

Kursorien säännöt

• Kursori on läpinäkymätön, enintään 512 merkin merkkijono. Älä jäsennä sitä äläkä muodosta sitä itse: sen muoto voi muuttua.
• Kursori kuuluu yhteen listaan ja yhteen suodatinjoukkoon. Vioittunut kursori, toisesta listasta peräisin oleva kursori tai eri suodattimilla lähetetty kursori palauttaa 400-vastauksen ja koodin api.cursor_invalid.
• Jokaisella listalla on kiinteä lajittelujärjestys, joka päättyy yksilölliseen avaimeen, joten jokainen kohde on täsmälleen yhdellä sivulla.
• Kursorien myötä lisätyt listat eivät palauta kokonaismäärää; listat, joissa total oli jo aiemmin, säilyttävät sen. Laske kohteet sitä mukaa kuin luet niitä, jos tarvitset kokonaismäärän.

Siirtymään perustuva sivutus

Jotkin listat hyväksyivät offset-parametrin jo ennen kursorien käyttöönottoa ja hyväksyvät sen edelleen, jotta olemassa olevat integraatiot toimivat. Suosi uudessa koodissa cursor-parametria. offset- ja cursor-parametreja ei voi yhdistää: molempien lähettäminen palauttaa 422-vastauksen ja koodin validation.failed.