İlgili nesneleri genişletme

Nesneler ilgili nesnelere kimlikle başvurur: bir kartta owner_id ve collection_id bulunur. İlgili nesnenin kendisine ihtiyaç duyduğunuzda ikinci bir istek yapmanız gerekmez. Nesneyi expand[] ile isteyin; nesne aynı yanıtta, expanded içinde gelir:

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"}
  }
}

Örnek kısaltılmıştır: genişletilmiş bir nesne, kendi okuma işlemindeki tüm alanlara sahiptir. Kimlik alanları yerinde kalır; bu yüzden expand[] kullanmayan kod öncekiyle aynı yanıtı alır.

Aşağıdaki işlemler ilgili nesneleri genişletir. Noktalı bir yol, genişletilmiş nesnenin bir bağlantısını genişletir; örneğin collection.default_owner, kartın koleksiyonunun varsayılan sorumlusudur.

İşlem	Yollar
`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`

Her bağlantı, ilgili nesneyi okuyan işlemin biçiminde gelir:

Bağlantı	`expanded` içinde ne gelir
`collection`	Koleksiyon, `GET /v1/collections` yanıtındaki gibi.
`owner`, `verifiers`, `default_owner`	Kullanıcı, `GET /v1/users` yanıtındaki gibi: kullanıcıları yönetebilen bir çağıran için tam satır, diğer çağıranlar için kısa satır (`brief=true`, yalnızca etkin kullanıcılar). `verifiers`, `verifier_ids` sırasındaki bir listedir.
`folders`	Kartın, koleksiyonunda çağıranın erişebildiği klasörleri; `path` olmadan `GET /v1/folders/{folder_id}` yanıtındaki gibi.
`card`	Kart, `GET /v1/cards` listesinin bir öğesi olarak.
`event`	Olay, `GET /v1/webhook-events/{event_id}` yanıtındaki gibi.

Listelerde

Bir liste için yolu data. ile başlatın: yol, sayfadaki her öğeye uygulanır. Bu, GET /v1/cards gibi dizi döndüren bir liste için de, öğelerini bir alanda tutan bir liste için de (GET /v1/jobs yanıtındaki jobs ya da teslim günlüğündeki items) aynıdır.

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 her bağlantıyı sayfanın tamamı için tek seferde yükler; bu yüzden bir listeyi genişletmenin maliyeti öğe başına bir istek değil, yaklaşık bir ek istek kadardır. Sonraki sayfanın imleci expand[] parametresine bağlı değildir; bu yüzden sonraki sayfada başka bağlantılar isteyebilirsiniz.

Kurallar

İstek başına en fazla 10 yol; her biri en fazla 2 bölüm derinlikte: listede data.owner, bir nesnede collection.default_owner.
Bilinmeyen bir yol, 10’dan fazla yol ya da 2 bölümden derin bir yol api.expand_invalid koduyla 400 döndürür. details.path yolu belirtir, details.reason ise neyin yanlış olduğunu söyler: unknown_path, too_deep ya da too_many_paths.
İlgili bir nesne yalnızca onu kendi isteğiyle okuyabilecek bir çağıran için genişletilir. Anahtarın o işlemin kapsamına sahip olması gerekir: kartlar, koleksiyonlar ve klasörler için cards:read, kullanıcılar için users:read, olaylar için webhooks:manage. Nesne çağıranın erişimine de açık olmalıdır; örneğin bazı koleksiyonlarla sınırlı bir anahtar için bu koleksiyonların içinde bulunmalıdır. Aksi hâlde bağlantı null olarak genişletilir; verifiers içinde ise o kullanıcının yerinde null bulunur. Kimliği yine de döndürülür. folders yalnızca çağıranın erişebildiği klasörleri listeler.
Özel kaynak anahtarı kartları okumaz; bu yüzden bu anahtarla bir belgenin card alanı her zaman null olur. Kartı almak için gönderim (push) API’sini import:write ve cards:read kapsamlarına sahip bir API anahtarıyla çağırın.
30 günden eski bir olay ve bir test teslimindeki olay null olarak genişletilir.
expand[] yanıta yalnızca veri ekler. İsteğin yaptığı işi hiçbir zaman değiştirmez.