Memperluas objek terkait

Objek merujuk ke objek terkait melalui ID: kartu memiliki owner_id dan collection_id. Jika Anda membutuhkan objek terkait itu sendiri, Anda tidak perlu mengirim permintaan kedua. Mintalah dengan expand[], dan objek itu datang dalam respons yang sama, di dalam 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"}
  }
}

Contoh ini dipersingkat: objek yang diperluas memiliki semua field dari operasi bacanya sendiri. Field ID tetap di tempatnya, jadi kode yang tidak memakai expand[] melihat respons yang sama seperti sebelumnya.

Operasi berikut memperluas objek terkait. Path dengan titik memperluas relasi dari objek yang diperluas, misalnya collection.default_owner adalah penanggung jawab default dari koleksi kartu tersebut.

Operasi	Path
`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`

Setiap relasi datang dalam bentuk yang sama seperti pada operasi yang membaca objek terkait:

Relasi	Yang datang di `expanded`
`collection`	Koleksi, seperti di `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Pengguna, seperti di `GET /v1/users`: baris lengkap untuk pemanggil yang boleh mengelola pengguna, baris ringkas (`brief=true`, hanya pengguna aktif) untuk pemanggil lain. `verifiers` adalah daftar dengan urutan `verifier_ids`.
`folders`	Folder kartu di koleksinya yang dapat dilihat pemanggil, seperti di `GET /v1/folders/{folder_id}` tanpa `path`.
`card`	Kartu, sebagai item dari `GET /v1/cards`.
`event`	Peristiwa, seperti di `GET /v1/webhook-events/{event_id}`.

Dalam daftar

Untuk daftar, awali path dengan data.: path itu berlaku untuk setiap item di halaman. Ini sama untuk daftar yang mengembalikan array, seperti GET /v1/cards, dan untuk daftar yang menyimpan itemnya di sebuah field, seperti jobs dari GET /v1/jobs atau items dari log pengiriman.

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 memuat setiap relasi untuk seluruh halaman sekaligus, jadi memperluas daftar kira-kira sama mahalnya dengan satu permintaan tambahan, bukan satu permintaan per item. Kursor halaman berikutnya tidak bergantung pada expand[], jadi Anda dapat meminta relasi lain di halaman berikutnya.

Aturan

Hingga 10 path per permintaan, masing-masing paling banyak 2 segmen: data.owner dalam daftar, collection.default_owner pada objek.
Path yang tidak dikenal, lebih dari 10 path, atau path yang lebih dari 2 segmen mengembalikan 400 dengan kode api.expand_invalid. details.path menyebut path-nya, dan details.reason menyebut masalahnya: unknown_path, too_deep, atau too_many_paths.
Objek terkait diperluas hanya untuk pemanggil yang dapat membacanya dengan permintaannya sendiri. Kunci memerlukan cakupan operasi itu: cards:read untuk kartu, koleksi, dan folder, users:read untuk pengguna, webhooks:manage untuk peristiwa. Objek juga harus terlihat oleh pemanggil, misalnya berada di dalam koleksi kunci yang dibatasi pada beberapa koleksi. Jika tidak, relasi diperluas sebagai null, dan di verifiers pengguna itu diganti null di tempatnya. ID-nya tetap dikembalikan. folders hanya mencantumkan folder yang dapat dilihat pemanggil.
Kunci sumber kustom tidak membaca kartu, jadi dengan kunci itu card dari sebuah dokumen selalu null. Untuk mendapatkan kartunya, panggil API push dengan kunci API yang memiliki cakupan import:write dan cards:read.
Peristiwa yang lebih lama dari 30 hari dan peristiwa dari pengiriman uji diperluas sebagai null.
expand[] hanya menambahkan data ke respons. Parameter ini tidak pernah mengubah apa yang dilakukan permintaan.