Разгъване на свързани обекти

Обектите сочат към свързаните обекти чрез 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[] само добавя данни към отговора. Той никога не променя действието на заявката.