Paginasi

Daftar di API Sursa dipaginasi dengan kursor: Anda meminta hingga limit item, dan respons memberi tahu cara mendapatkan halaman berikutnya. Anda tidak pernah menghitung offset, dan item tidak berulang atau hilang di antara halaman ketika data berubah sementara itu.

Daftar mengembalikan kursor berikutnya dengan salah satu dari dua cara, tergantung bentuk responsnya. Halaman setiap endpoint di referensi API menunjukkan cara mana yang dipakainya.

Daftar dengan amplop data

Daftar yang ditambahkan untuk API publik, seperti umpan peristiwa, mengembalikan objek dengan item di 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
}

Jika has_more bernilai true, minta halaman berikutnya dengan cursor diisi next_cursor dan penyaring yang sama:

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

Daftar yang sudah ada sebelum kursor dan mengembalikan objek mempertahankan amplopnya sendiri (misalnya {"items": […], "total": 120}). Daftar itu mendapat next_cursor dan has_more di objek yang sama; item tetap di tempatnya semula.

Daftar yang mengembalikan array

Beberapa daftar mengembalikan array JSON polos, misalnya GET /v1/collections. Bentuk responsnya tidak dapat berubah, jadi halaman berikutnya datang di header:

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 dengan rel="next" adalah alamat lengkap halaman berikutnya; X-Next-Cursor adalah kursor yang sama saja.
• Tidak ada Link dengan rel="next" dan tidak ada X-Next-Cursor berarti ini halaman terakhir.
• Tanpa limit, daftar ini mengembalikan setiap item dalam satu respons, seperti selama ini. Berikan limit untuk mempaginasinya; kursor mengingat ukuran halaman, jadi permintaan berikutnya boleh tidak menyertakan limit.
• GET /v1/cards adalah pengecualian: daftar ini selalu mengembalikan halaman, secara default 200 kartu dan hingga 1000 dengan limit, jadi ikuti X-Next-Cursor bahkan tanpa 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;
  }
}

Umpan peristiwa

Umpan peristiwa GET /v1/webhook-events adalah sebuah log, jadi paginasinya sedikit berbeda:

• Peristiwa diurutkan secara menaik, yang terlama lebih dulu.
• next_cursor dikembalikan di setiap halaman, bahkan saat has_more bernilai false. Simpan kursor itu, dan minta lagi nanti dengan kursor yang sama untuk mendapatkan peristiwa yang terjadi sejak saat itu. Umpan ini adalah antrean yang dapat Anda baca sesuai kecepatan Anda sendiri.
• Peristiwa muncul di umpan sekitar satu detik setelah perubahan yang digambarkannya, dan tidak pernah sebelum peristiwa yang sudah dibaca.
• Umpan berisi peristiwa seluruh organisasi, jadi membacanya memerlukan kunci dengan peran admin dan cakupan webhooks:manage.

Ekspor ke gudang data menunjukkan loop polling yang lengkap.

Aturan kursor

• Kursor adalah string buram hingga 512 karakter. Jangan mengurainya atau membuatnya sendiri: formatnya dapat berubah.
• Kursor milik satu daftar dan satu kumpulan penyaring. Kursor yang rusak, berasal dari daftar lain, atau dikirim dengan penyaring yang berbeda mengembalikan 400 dengan kode api.cursor_invalid.
• Setiap daftar memiliki urutan tetap yang diakhiri dengan kunci unik, jadi setiap item muncul tepat di satu halaman.
• Daftar yang ditambahkan bersama kursor tidak mengembalikan jumlah total; daftar yang sebelumnya memiliki total tetap mempertahankannya. Hitung item sambil membaca jika Anda membutuhkan totalnya.

Paginasi offset

Beberapa daftar menerima offset sebelum kursor diperkenalkan, dan masih menerimanya, agar integrasi yang sudah ada tetap berfungsi. Utamakan cursor dalam kode baru. offset dan cursor tidak dapat digabungkan: mengirim keduanya mengembalikan 422 dengan kode validation.failed.