Sayfalama

Sursa API’nin listeleri bir imleçle sayfalanır: en fazla limit kadar öğe istersiniz ve yanıt size sonraki sayfayı nasıl alacağınızı söyler. Hiçbir zaman ofset hesaplamanız gerekmez; bu arada veriler değişse bile öğeler sayfalar arasında tekrarlanmaz ya da kaybolmaz.

Bir liste, yanıtının biçimine bağlı olarak sonraki imlecini iki yoldan biriyle döndürür. API başvurusunda her uç noktanın sayfası hangisini kullandığını gösterir.

Öğeleri data zarfında döndüren listeler

Herkese açık API için eklenen listeler (örneğin olay beslemesi), öğeleri data alanında bulunan bir nesne döndürür:

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
}

has_more değeri true olduğunda sonraki sayfayı, cursor parametresine next_cursor değerini vererek ve aynı filtrelerle isteyin:

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

İmleçlerden önce var olan ve nesne döndüren listeler kendi zarflarını korur (örneğin {"items": […], "total": 120}). Bu listelerde next_cursor ve has_more aynı nesneye eklenir; öğeler bulundukları yerde kalır.

Dizi döndüren listeler

Birkaç liste yalın bir JSON dizisi döndürür, örneğin GET /v1/collections. Bu listelerin yanıt biçimi değişemez, bu yüzden sonraki sayfa bunun yerine başlıklarda gelir:

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 başlığı (rel="next" ile) sonraki sayfanın tam adresidir; X-Next-Cursor aynı imlecin tek başına hâlidir.
• rel="next" içeren bir Link başlığı ve X-Next-Cursor yoksa bu son sayfadır.
• limit olmadan bu listeler, her zaman olduğu gibi tüm öğeleri tek yanıtta döndürür. Sayfalamak için limit gönderin; imleç sayfa boyutunu hatırlar, bu yüzden sonraki istekte limit gönderilmeyebilir.
• GET /v1/cards bunun istisnasıdır: her zaman sayfa döndürür (varsayılan olarak 200 kart, limit ile en fazla 1000), bu yüzden limit olmadan da X-Next-Cursor başlığını izleyin.

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

Olay beslemesi

GET /v1/webhook-events olay beslemesi bir günlüktür, bu yüzden biraz farklı sayfalanır:

• Olaylar artan sıradadır, en eskisi önce gelir.
• next_cursor, has_more değeri false olduğunda bile her sayfada döndürülür. Bu değeri saklayın ve o zamandan beri gerçekleşen olayları almak için daha sonra aynı imleçle yeniden isteyin. Besleme, kendi hızınızda okuyabileceğiniz bir kuyruktur.
• Bir olay, anlattığı değişiklikten yaklaşık bir saniye sonra beslemede görünür ve hiçbir zaman daha önce okunmuş bir olaydan önce yer almaz.
• Besleme tüm kuruluşun olaylarını içerir; bu yüzden onu okumak için admin rolüne ve webhooks:manage kapsamına sahip bir anahtar gerekir.

Veri ambarına aktarma kılavuzu eksiksiz bir yoklama döngüsü gösterir.

İmleç kuralları

• İmleç, en fazla 512 karakterlik opak bir dizedir. Onu ayrıştırmayın ya da kendiniz oluşturmayın: biçimi değişebilir.
• Bir imleç tek bir listeye ve tek bir filtre kümesine aittir. Bozulmuş, başka bir listeden gelen ya da farklı filtrelerle gönderilen bir imleç api.cursor_invalid koduyla 400 döndürür.
• Her listenin benzersiz bir anahtarla biten sabit bir sıralama düzeni vardır; böylece her öğe tam olarak bir sayfada görünür.
• İmleçlerle birlikte eklenen listeler toplam sayı döndürmez; daha önce total alanı olan listeler onu korur. Toplama ihtiyacınız varsa öğeleri ilerledikçe sayın.

Ofset ile sayfalama

Bazı listeler, imleçler kullanılmaya başlanmadan önce offset parametresini kabul ediyordu ve mevcut entegrasyonlar çalışmaya devam etsin diye hâlâ kabul ediyor. Yeni kodda cursor tercih edin. offset ve cursor birlikte kullanılamaz: ikisini birden göndermek validation.failed koduyla 422 döndürür.