पेजिनेशन

Sursa API की सूचियाँ कर्सर से पेजों में बँटती हैं: आप ज़्यादा से ज़्यादा limit आइटम माँगते हैं, और रिस्पॉन्स बताता है कि अगला पेज कैसे पाएँ। आपको कभी ऑफ़सेट की गिनती नहीं करनी पड़ती, और इस बीच डेटा बदल जाए, तब भी पेजों के बीच आइटम न दोहराए जाते हैं, न छूटते हैं।

सूची अपने रिस्पॉन्स के ढाँचे के आधार पर अगला कर्सर दो में से किसी एक तरीक़े से लौटाती है। API रेफ़रेंस में हर एंडपॉइंट का पेज दिखाता है कि वह कौन-सा तरीक़ा इस्तेमाल करता है।

data लिफ़ाफ़े वाली सूचियाँ

पब्लिक API के लिए जोड़ी गई सूचियाँ, जैसे इवेंट फ़ीड, एक ऑब्जेक्ट लौटाती हैं, जिसमें आइटम 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
}

जब has_more का मान true हो, तो अगला पेज cursor में next_cursor डालकर और वही फ़िल्टर रखकर माँगें:

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

कर्सर से पहले से मौजूद और ऑब्जेक्ट लौटाने वाली सूचियाँ अपना ख़ुद का लिफ़ाफ़ा रखती हैं (उदाहरण के लिए, {"items": […], "total": 120})। उन्हें उसी ऑब्जेक्ट में next_cursor और has_more मिलते हैं; आइटम वहीं रहते हैं, जहाँ थे।

ऐरे लौटाने वाली सूचियाँ

कुछ सूचियाँ सादा JSON ऐरे लौटाती हैं, उदाहरण के लिए GET /v1/collections। उनके रिस्पॉन्स का ढाँचा नहीं बदल सकता, इसलिए अगला पेज इसके बजाय हेडर में आता है:

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

• rel="next" वाला Link अगले पेज का पूरा पता है; X-Next-Cursor अलग से वही कर्सर है।
• अगर rel="next" वाला Link और X-Next-Cursor नहीं हैं, तो यह आख़िरी पेज है।
• limit के बिना ये सूचियाँ हर आइटम एक ही रिस्पॉन्स में लौटाती हैं, जैसे हमेशा लौटाती थीं। उन्हें पेजों में पढ़ने के लिए limit भेजें; कर्सर पेज का आकार याद रखता है, इसलिए अगली रिक्वेस्ट में limit छोड़ा जा सकता है।
• GET /v1/cards इसका अपवाद है: यह हमेशा पेज लौटाता है, डिफ़ॉल्ट रूप से 200 कार्ड और limit के साथ 1000 तक, इसलिए limit के बिना भी X-Next-Cursor का पालन करें।

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

इवेंट फ़ीड

इवेंट फ़ीड GET /v1/webhook-events एक लॉग है, इसलिए इसका पेजिनेशन थोड़ा अलग है:

• इवेंट बढ़ते क्रम में हैं, सबसे पुराना पहले।
• next_cursor हर पेज पर लौटाया जाता है, तब भी जब has_more का मान false हो। इसे सेव करें, और उसके बाद हुए इवेंट पाने के लिए बाद में उसी कर्सर के साथ फिर से माँगें। फ़ीड एक कतार है, जिसे आप अपनी रफ़्तार से पढ़ सकते हैं।
• इवेंट उस बदलाव के लगभग एक सेकंड के अंदर फ़ीड में आ जाता है, जिसका वह वर्णन करता है, और किसी पहले से पढ़े गए इवेंट से पहले कभी नहीं आता।
• फ़ीड में पूरे संगठन के इवेंट होते हैं, इसलिए उसे पढ़ने के लिए admin रोल और स्कोप webhooks:manage वाली कुंजी चाहिए।

डेटा वेयरहाउस में एक्सपोर्ट में पूरा पोलिंग लूप दिखाया गया है।

कर्सर के नियम

• कर्सर 512 अक्षरों तक की अपारदर्शी स्ट्रिंग है। इसे पार्स न करें और ख़ुद न बनाएँ: इसका फ़ॉर्मेट बदल सकता है।
• कर्सर एक सूची और फ़िल्टर के एक सेट का होता है। ख़राब कर्सर, किसी दूसरी सूची का कर्सर, या अलग फ़िल्टर के साथ भेजा गया कर्सर कोड api.cursor_invalid के साथ 400 लौटाता है।
• हर सूची का एक तय सॉर्ट क्रम होता है, जो किसी यूनिक कुंजी पर ख़त्म होता है, इसलिए हर आइटम ठीक एक पेज पर आता है।
• कर्सर के साथ जोड़ी गई सूचियाँ कुल संख्या नहीं लौटातीं; जिन सूचियों में पहले total था, उनमें वह बना रहता है। अगर कुल संख्या चाहिए, तो पढ़ते समय आइटम गिनते जाएँ।

ऑफ़सेट पेजिनेशन

कुछ सूचियाँ कर्सर आने से पहले offset स्वीकार करती थीं, और अब भी करती हैं, ताकि मौजूदा इंटीग्रेशन काम करते रहें। नए कोड में cursor इस्तेमाल करें। offset और cursor को साथ इस्तेमाल नहीं किया जा सकता: दोनों भेजने पर कोड validation.failed के साथ 422 लौटता है।