जुड़े ऑब्जेक्ट एक्सपैंड करना

ऑब्जेक्ट जुड़े ऑब्जेक्ट का हवाला ID से देते हैं: कार्ड में owner_id और collection_id होते हैं। जब आपको जुड़ा ऑब्जेक्ट ख़ुद चाहिए, तो दूसरी रिक्वेस्ट भेजने की ज़रूरत नहीं है। उसे expand[] से माँगें, और वह उसी रिस्पॉन्स में, expanded के अंदर, आ जाता है:

curl -G https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "expand[]=owner" \
  --data-urlencode "expand[]=collection"

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "owner_id": 7,
  "collection_id": 3,
  "expanded": {
    "owner": {"id": 7, "username": "anna", "display_name": "Anna Petrova", "role": "editor"},
    "collection": {"id": 3, "name": "support", "title": "Support"}
  }
}

उदाहरण छोटा किया गया है: एक्सपैंड किए गए ऑब्जेक्ट में उसके अपने पढ़ने वाले ऑपरेशन के सभी फ़ील्ड होते हैं। ID वाले फ़ील्ड अपनी जगह पर रहते हैं, इसलिए जो कोड expand[] इस्तेमाल नहीं करता, उसे पहले जैसा ही रिस्पॉन्स मिलता है।

ये ऑपरेशन जुड़े ऑब्जेक्ट एक्सपैंड करते हैं। बिंदु वाला पाथ एक्सपैंड किए गए ऑब्जेक्ट के किसी लिंक को एक्सपैंड करता है, उदाहरण के लिए collection.default_owner कार्ड के कलेक्शन का डिफ़ॉल्ट ज़िम्मेदार व्यक्ति है।

ऑपरेशन	पाथ
`GET /v1/cards/{card_id}`, `GET /v1/cards-by-external-id/{external_id}`	`collection`, `owner`, `verifiers`, `folders`, `collection.default_owner`
`GET /v1/cards`	`data.collection`, `data.owner`, `data.verifiers`, `data.folders`
`GET /v1/jobs/{job_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/jobs`	`data.card`
`GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}`	`event`
`GET /v1/webhooks/{webhook_id}/deliveries`	`data.event`
`GET /v1/push/sources/{source_id}/documents/{external_id}`	`card`, `card.collection`, `card.owner`, `card.verifiers`, `card.folders`
`GET /v1/push/sources/{source_id}/syncs/{sync_number}/documents`	`data.card`

हर लिंक उसी रूप में आता है, जिसमें उसे जुड़ा ऑब्जेक्ट पढ़ने वाला ऑपरेशन लौटाता है:

लिंक	`expanded` में क्या आता है
`collection`	कलेक्शन, जैसा `GET /v1/collections` में।
`owner`, `verifiers`, `default_owner`	यूज़र, जैसा `GET /v1/users` में: यूज़र मैनेज कर सकने वाले कॉल करने वाले के लिए पूरी पंक्ति, बाक़ी कॉल करने वालों के लिए छोटी पंक्ति (`brief=true`, सिर्फ़ सक्रिय यूज़र)। `verifiers` एक सूची है, `verifier_ids` के क्रम में।
`folders`	कार्ड के कलेक्शन में उसके वे फ़ोल्डर, जो कॉल करने वाले को दिखते हैं, जैसे `GET /v1/folders/{folder_id}` में, `path` के बिना।
`card`	कार्ड, `GET /v1/cards` के एक आइटम के रूप में।
`event`	इवेंट, जैसा `GET /v1/webhook-events/{event_id}` में।

सूचियों में

सूची के लिए पाथ data. से शुरू करें: यह पेज के हर आइटम पर लागू होता है। यह ऐरे लौटाने वाली सूची, जैसे GET /v1/cards, और अपने आइटम किसी फ़ील्ड में रखने वाली सूची, जैसे GET /v1/jobs का jobs या डिलीवरी लॉग का items, दोनों के लिए एक जैसा है।

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "expand[]=data.owner" \
  --data-urlencode "expand[]=data.collection"

Sursa हर लिंक को पूरे पेज के लिए एक साथ लोड करता है, इसलिए सूची को एक्सपैंड करने में लगभग एक अतिरिक्त रिक्वेस्ट जितना ख़र्च आता है, हर आइटम के लिए एक रिक्वेस्ट जितना नहीं। अगले पेज का कर्सर expand[] पर निर्भर नहीं करता, इसलिए अगले पेज पर आप दूसरे लिंक माँग सकते हैं।

नियम

एक रिक्वेस्ट में 10 पाथ तक, हर एक ज़्यादा से ज़्यादा 2 हिस्सों का: सूची में data.owner, ऑब्जेक्ट पर collection.default_owner।
अनजान पाथ, 10 से ज़्यादा पाथ या 2 हिस्सों से ज़्यादा गहरा पाथ कोड api.expand_invalid के साथ 400 लौटाता है। details.path पाथ का नाम बताता है, और details.reason बताता है कि क्या ग़लत है: unknown_path, too_deep या too_many_paths।
जुड़ा ऑब्जेक्ट सिर्फ़ उसी कॉल करने वाले के लिए एक्सपैंड होता है, जो उसे उसकी अपनी रिक्वेस्ट से पढ़ सकता था। कुंजी के पास उस ऑपरेशन का स्कोप होना चाहिए: कार्ड, कलेक्शन और फ़ोल्डर के लिए cards:read, यूज़र के लिए users:read, इवेंट के लिए webhooks:manage। ऑब्जेक्ट कॉल करने वाले को दिखना भी चाहिए, उदाहरण के लिए कुछ कलेक्शन तक सीमित कुंजी के कलेक्शन के अंदर। नहीं तो लिंक null के रूप में एक्सपैंड होता है, और verifiers में उस यूज़र की जगह null होता है। उसकी ID फिर भी लौटाई जाती है। folders में सिर्फ़ वे फ़ोल्डर आते हैं, जो कॉल करने वाले को दिखते हैं।
कस्टम स्रोत की कुंजी कार्ड नहीं पढ़ती, इसलिए उसके साथ दस्तावेज़ का card हमेशा null होता है। कार्ड पाने के लिए स्कोप import:write और cards:read वाली API कुंजी से पुश API कॉल करें।
30 दिन से पुराना इवेंट और टेस्ट डिलीवरी का इवेंट null के रूप में एक्सपैंड होते हैं।
expand[] रिस्पॉन्स में सिर्फ़ डेटा जोड़ता है। यह कभी नहीं बदलता कि रिक्वेस्ट क्या करती है।