การขยายออบเจ็กต์ที่เกี่ยวข้อง

ออบเจ็กต์อ้างถึงออบเจ็กต์ที่เกี่ยวข้องด้วย 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 และกับรายการที่เก็บรายการไว้ในฟิลด์ เช่น jobs ของ GET /v1/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 ส่วนจะได้การตอบกลับ 400 พร้อมรหัส api.expand_invalid details.path ระบุพาธ และ details.reason บอกว่าผิดอย่างไร: unknown_path too_deep หรือ too_many_paths
ออบเจ็กต์ที่เกี่ยวข้องจะขยายให้เฉพาะผู้เรียกที่อ่านออบเจ็กต์นั้นได้ด้วยคำขอของออบเจ็กต์นั้นเอง คีย์ต้องมีขอบเขตสิทธิ์ของการดำเนินการนั้น: cards:read สำหรับการ์ด คอลเลกชัน และโฟลเดอร์ users:read สำหรับผู้ใช้ และ webhooks:manage สำหรับอีเวนต์ ผู้เรียกต้องมองเห็นออบเจ็กต์นั้นด้วย เช่น ออบเจ็กต์ต้องอยู่ในคอลเลกชันของคีย์ที่จำกัดไว้เฉพาะบางคอลเลกชัน มิฉะนั้นการเชื่อมโยงจะขยายเป็น null และใน verifiers ผู้ใช้คนนั้นจะเป็น null ในตำแหน่งของตน แต่ยังคงส่งคืน ID ของออบเจ็กต์นั้น folders แสดงเฉพาะโฟลเดอร์ที่ผู้เรียกมองเห็นได้
คีย์แหล่งข้อมูลอ่านการ์ดไม่ได้ เมื่อใช้คีย์นี้ card ของเอกสารจึงเป็น null เสมอ หากต้องการการ์ด ให้เรียก API สำหรับส่ง (push) ด้วยคีย์ API ที่มีขอบเขตสิทธิ์ import:write และ cards:read
อีเวนต์ที่เก่ากว่า 30 วันและอีเวนต์ของการส่งทดสอบจะขยายเป็น null
expand[] เพียงเพิ่มข้อมูลลงในการตอบกลับ และไม่เปลี่ยนสิ่งที่คำขอทำเลย