Розгортання пов’язаних об’єктів

Об’єкти посилаються на пов’язані об’єкти за ідентифікатором: картка має 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"}
  }
}

Приклад скорочено: розгорнутий об’єкт має всі поля власної операції читання. Поля з ідентифікаторами лишаються на своїх місцях, тож код, який не використовує 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. Його ідентифікатор усе одно повертається. folders містить лише папки, які бачить відправник запитів.
Ключ власного джерела не читає картки, тож із ним card документа завжди null. Щоб отримати картку, викликайте push API з ключем API, що має області доступу import:write і cards:read.
Подія, старша за 30 днів, і подія тестової доставки розгортаються як null.
expand[] лише додає дані до відповіді. Він ніколи не змінює того, що робить запит.