Lapozás

A Sursa API listái kurzorral lapozhatók: legfeljebb limit elemet kérsz, és a válasz megmondja, hogyan kapod meg a következő oldalt. Soha nem kell eltolást számolnod, és ha közben változnak az adatok, az elemek nem ismétlődnek és nem vesznek el az oldalak között.

A lista kétféleképpen adhatja vissza a következő kurzort, a válasza szerkezetétől függően. Az API-referencia minden végpontoldala megmutatja, melyiket használja.

Listák data-borítékkal

A nyilvános API-hoz hozzáadott listák, például az eseménycsatorna, olyan objektumot adnak vissza, amelyben az elemek a data mezőben vannak:

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
}

Ha a has_more értéke true, a következő oldalt úgy kérd le, hogy a cursor értéke a next_cursor legyen, és ugyanazokat a szűrőket add meg:

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

A kurzorok előtt már létező, objektumot visszaadó listák megtartják a saját borítékukat (például {"items": […], "total": 120}). Ezek ugyanabban az objektumban kapják meg a next_cursor és a has_more mezőt; az elemek ott maradnak, ahol voltak.

Tömböt visszaadó listák

Néhány lista puszta JSON-tömböt ad vissza, például a GET /v1/collections. Ezek válaszszerkezete nem változhat, ezért a következő oldal adatai fejlécekben érkeznek:

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

• A rel="next" értékű Link fejléc a következő oldal teljes címe; az X-Next-Cursor ugyanez a kurzor önmagában.
• Ha nincs rel="next" értékű Link és nincs X-Next-Cursor fejléc, ez az utolsó oldal.
• limit nélkül ezek a listák minden elemet egyetlen válaszban adnak vissza, ahogy mindig is. A lapozáshoz add meg a limit paramétert; a kurzor megjegyzi az oldalméretet, így a következő kérésből a limit elhagyható.
• A GET /v1/cards kivétel: mindig oldalakat ad vissza, alapértelmezés szerint 200 kártyát, a limit paraméterrel legfeljebb 1000-et, ezért limit nélkül is kövesd az X-Next-Cursor fejlécet.

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

Az eseménycsatorna

A GET /v1/webhook-events eseménycsatorna napló, ezért egy kicsit másképp lapoz:

• Az események növekvő sorrendben vannak, a legrégebbi az első.
• A next_cursor minden oldalon megérkezik, akkor is, ha a has_more értéke false. Tárold el, és később kérdezz le újra ugyanazzal a kurzorral, hogy megkapd az azóta történt eseményeket. A csatorna olyan sor, amelyet a saját tempódban olvashatsz.
• Az esemény nagyjából egy másodpercen belül megjelenik a csatornában az általa leírt változás után, és soha nem egy már beolvasott esemény előtt.
• A csatorna az egész szervezet eseményeit tartalmazza, ezért az olvasásához admin szerepkörű és webhooks:manage hatókörű kulcs kell.

Az Exportálás adattárházba útmutató egy teljes lekérdezési ciklust mutat be.

A kurzorok szabályai

• A kurzor legfeljebb 512 karakteres átlátszatlan karakterlánc. Ne bontsd elemeire, és ne állítsd össze magad: a formátuma változhat.
• A kurzor egy listához és egy szűrőkészlethez tartozik. A sérült, más listából származó vagy más szűrőkkel küldött kurzorra a válasz 400 az api.cursor_invalid kóddal.
• Minden listának rögzített rendezési sorrendje van, amely egyedi kulccsal végződik, így minden elem pontosan egy oldalon jelenik meg.
• A kurzorokkal együtt bevezetett listák nem adnak vissza teljes darabszámot; azok a listák, amelyeknek korábban volt total mezőjük, megtartják. Ha szükséged van az összesre, számold az elemeket menet közben.

Eltolásos (offset) lapozás

Néhány lista már a kurzorok bevezetése előtt elfogadta az offset paramétert, és továbbra is elfogadja, hogy a meglévő integrációk tovább működjenek. Új kódban a cursor paramétert részesítsd előnyben. Az offset és a cursor nem kombinálható: ha mindkettőt elküldöd, a válasz 422 a validation.failed kóddal.