ऑब्जेक्ट के ID

API के हर ऑब्जेक्ट का एक id होता है। जब आपको ऑब्जेक्ट पर वापस आना हो, तो इसे अपने सिस्टम में सेव करें: नाम और शीर्षक बदल सकते हैं, ID कभी नहीं बदलती।

ID को अपारदर्शी मानें (इसके मान का मतलब न निकालें)। उन्हें पार्स न करें, और टाइप के अलावा किसी फ़ॉर्मेट की उम्मीद न करें: स्ट्रिंग ID कोई भी स्ट्रिंग हो सकती है, उतनी लंबाई तक जितनी उसका फ़ील्ड अनुमति देता है।

ऐसे नए तरह के ऑब्जेक्ट, जिनका हवाला आप शायद अपने सिस्टम से देंगे, स्ट्रिंग ID पाते हैं: एक छोटा प्रीफ़िक्स, जो ऑब्जेक्ट का प्रकार बताता है, और उसके बाद 32 हेक्साडेसिमल अक्षर।

ऑब्जेक्ट के बीच हवाले

ऑब्जेक्ट एक-दूसरे का हवाला ID से देते हैं, <object>_id नाम वाले फ़ील्ड में: collection_id, owner_id, folder_id। जुड़ा ऑब्जेक्ट उसी रिस्पॉन्स में पाने के लिए expand[] इस्तेमाल करें।

ID लेने वाले पाथ पैरामीटर के नाम भी इसी तरह होते हैं: {card_id}, {webhook_id}, {upload_id}।

ID से कलेक्शन

कलेक्शन के पास id भी होता है और एक यूनिक name भी, जैसे support। जो पाथ ID को प्राथमिकता मिलने से पहले से मौजूद थे, वे कलेक्शन का नाम लेते हैं:

GET /v1/collections/support/stats

यही पाथ ID भी लेते हैं, id:<number> के रूप में लिखी हुई:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

नए कोड में id: वाला रूप इस्तेमाल करें: एडमिन कलेक्शन का नाम बदल सकता है, पर उसकी ID वही रहती है। सिर्फ़ अंकों वाला सेगमेंट, जैसे /v1/collections/3, अब भी 3 नाम वाले कलेक्शन का मतलब है। कलेक्शन के नाम में : नहीं हो सकता, इसलिए दोनों रूप कभी आपस में नहीं मिलते।

रिक्वेस्ट बॉडी और क्वेरी पैरामीटर में collection_id पुराने collection (नाम) के साथ मौजूद है। दोनों भेजने पर collection_id को प्राथमिकता मिलती है। जो collection_id संगठन में मौजूद नहीं है, या जिसे देखने की अनुमति कुंजी के पास नहीं है, वह कोड collections.not_found के साथ 404 लौटाता है।

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

आपकी अपनी ID

कार्ड external_id में उस रिकॉर्ड की ID रख सकते हैं, जिससे वे आपके सिस्टम में बने हैं: 512 अक्षरों तक, संगठन के कार्ड में यूनिक। इसके साथ आपको कार्ड की Sursa ID कभी सेव नहीं करनी पड़ती:

जब external_id पाथ का हिस्सा हो, तो उसे URL-एनकोड करें: crm/A-1042 बन जाता है crm%2FA-1042।

कस्टम स्रोत के दस्तावेज़ों का अपने स्रोत के अंदर अपना external_id होता है। दोनों आपस में नहीं टकराते: कस्टम स्रोत का कार्ड दस्तावेज़ को उसके स्रोत में फिर से भेजकर बदला जाता है, PUT /v1/cards-by-external-id/… से नहीं, जो ऐसे में कोड cards.managed_by_source के साथ 409 लौटाता है।