Stránkovanie

Zoznamy Sursa API sa stránkujú kurzorom: vyžiadate si najviac limit položiek a odpoveď vám povie, ako získať ďalšiu stránku. Posuny nikdy nepočítate a položky sa medzi stránkami neopakujú ani nestrácajú, ani keď sa medzitým údaje zmenia.

Zoznam vracia ďalší kurzor jedným z dvoch spôsobov podľa tvaru svojej odpovede. Ktorý z nich používa, ukazuje stránka každej operácie v referencii API.

Zoznamy s obálkou data

Zoznamy pridané pre verejné API, napríklad kanál udalostí, vracajú objekt s položkami v 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
}

Keď je has_more rovné true, vyžiadajte si ďalšiu stránku s cursor nastaveným na next_cursor a s rovnakými filtrami:

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

Zoznamy, ktoré existovali pred zavedením kurzorov a vracajú objekt, si ponechávajú vlastnú obálku (napríklad {"items": […], "total": 120}). V tom istom objekte dostanú next_cursor a has_more; položky zostávajú tam, kde boli.

Zoznamy, ktoré vracajú pole

Niekoľko zoznamov vracia holé pole JSON, napríklad GET /v1/collections. Tvar ich odpovede sa nemôže zmeniť, preto ďalšia stránka prichádza v hlavičkách:

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 s rel="next" je úplná adresa ďalšej stránky; X-Next-Cursor je ten istý kurzor samostatne.
• Ak chýba Link s rel="next" aj X-Next-Cursor, ide o poslednú stránku.
• Bez limit vracajú tieto zoznamy všetky položky v jednej odpovedi, ako vždy. Ak ich chcete stránkovať, odošlite limit; kurzor si veľkosť stránky pamätá, takže ďalšia požiadavka môže limit vynechať.
• GET /v1/cards je výnimka: vždy vracia stránky, predvolene 200 kariet a s limit najviac 1000, preto sledujte X-Next-Cursor aj bez 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;
  }
}

Kanál udalostí

Kanál udalostí GET /v1/webhook-events je log, preto sa stránkuje trochu inak:

• Udalosti sú vo vzostupnom poradí, najstaršie prvé.
• next_cursor sa vracia na každej stránke, aj keď je has_more rovné false. Uložte si ho a neskôr sa opýtajte znova s tým istým kurzorom, aby ste dostali udalosti, ktoré sa medzitým stali. Kanál je front, ktorý môžete čítať vlastným tempom.
• Udalosť sa v kanáli objaví približne do sekundy od zmeny, ktorú opisuje, a nikdy nie pred udalosťou, ktorá už bola prečítaná.
• Kanál obsahuje udalosti celej organizácie, preto jeho čítanie vyžaduje kľúč s rolou admin a rozsahom webhooks:manage.

Export do dátového skladu ukazuje úplnú slučku dopytovania.

Pravidlá pre kurzory

• Kurzor je nepriehľadný reťazec s dĺžkou najviac 512 znakov. Neanalyzujte ho ani ho nevytvárajte sami: jeho formát sa môže zmeniť.
• Kurzor patrí jednému zoznamu a jednej sade filtrov. Kurzor, ktorý je poškodený, pochádza z iného zoznamu alebo sa posiela s inými filtrami, vráti 400 s kódom api.cursor_invalid.
• Každý zoznam má pevné poradie zoradenia, ktoré končí jedinečným kľúčom, takže každá položka sa objaví práve na jednej stránke.
• Zoznamy pridané spolu s kurzormi nevracajú celkový počet; zoznamy, ktoré total mali už predtým, si ho ponechávajú. Ak potrebujete súčet, počítajte položky priebežne.

Stránkovanie posunom (offset)

Niektoré zoznamy prijímali offset pred zavedením kurzorov a prijímajú ho naďalej, aby existujúce integrácie fungovali. V novom kóde uprednostnite cursor. offset a cursor nemožno kombinovať: odoslanie oboch vráti 422 s kódom validation.failed.