Straničenje

Popisi Sursa API-ja straniče se pomoću kursora: tražite do limit stavki, a odgovor vam kaže kako dohvatiti sljedeću stranicu. Pomake nikada ne izračunavate, a stavke se između stranica ne ponavljaju i ne nestaju kad se podaci u međuvremenu promijene.

Popis vraća svoj sljedeći kursor na jedan od dva načina, ovisno o obliku svojeg odgovora. Stranica svake operacije u referenci API-ja pokazuje koji način koristi.

Popisi s omotnicom data

Popisi dodani za javni API, kao što je feed događaja, vraćaju objekt sa stavkama u 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
}

Kad je has_more jednako true, zatražite sljedeću stranicu s cursor postavljenim na next_cursor i istim filtrima:

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

Popisi koji su postojali prije kursora i vraćaju objekt zadržavaju vlastitu omotnicu (na primjer {"items": […], "total": 120}). Oni dobivaju next_cursor i has_more u istom objektu; stavke ostaju gdje su i bile.

Popisi koji vraćaju niz

Nekoliko popisa vraća goli JSON niz, na primjer GET /v1/collections. Oblik njihova odgovora ne može se promijeniti, pa sljedeća stranica umjesto toga stiže u zaglavljima:

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" puna je adresa sljedeće stranice; X-Next-Cursor je isti kursor zasebno.
• Ako nema zaglavlja Link s rel="next" ni X-Next-Cursor, to je posljednja stranica.
• Bez limit ovi popisi vraćaju sve stavke u jednom odgovoru, kao i uvijek. Proslijedite limit da biste ih straničili; kursor pamti veličinu stranice, pa sljedeći zahtjev smije izostaviti limit.
• GET /v1/cards je iznimka: uvijek vraća stranice, zadano po 200 kartica, a s limit do 1000, pa pratite X-Next-Cursor i 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;
  }
}

Feed događaja

Feed događaja GET /v1/webhook-events je zapisnik, pa se straniči malo drukčije:

• Događaji su poredani uzlazno, najstariji prvi.
• next_cursor vraća se na svakoj stranici, čak i kad je has_more jednako false. Pohranite ga i kasnije ponovno pošaljite zahtjev s istim kursorom da biste dobili događaje koji su se dogodili u međuvremenu. Feed je red koji možete čitati vlastitim tempom.
• Događaj se u feedu pojavljuje otprilike unutar jedne sekunde od promjene koju opisuje i nikada prije događaja koji je već pročitan.
• Feed sadrži događaje cijele organizacije, pa je za njegovo čitanje potreban ključ s ulogom admin i opsegom webhooks:manage.

Izvoz u skladište podataka prikazuje potpunu petlju periodične provjere.

Pravila za kursore

• Kursor je neproziran niz znakova duljine do 512 znakova. Ne raščlanjujte ga i ne sastavljajte ga sami: njegov se format može promijeniti.
• Kursor pripada jednom popisu i jednom skupu filtara. Kursor koji je oštećen, potječe s drugog popisa ili je poslan s drugim filtrima vraća 400 s kodom api.cursor_invalid.
• Svaki popis ima nepromjenjiv redoslijed sortiranja koji završava jedinstvenim ključem, pa se svaka stavka pojavljuje na točno jednoj stranici.
• Popisi dodani s kursorima ne vraćaju ukupan broj; popisi koji su prije imali total zadržavaju ga. Ako vam treba ukupan broj, brojite stavke usput.

Straničenje pomakom (offset)

Neki su popisi prihvaćali offset prije uvođenja kursora i još ga prihvaćaju, kako bi postojeće integracije nastavile raditi. U novom kodu prednost dajte parametru cursor. offset i cursor ne mogu se kombinirati: slanje obaju vraća 422 s kodom validation.failed.