Раскрытие связанных объектов

Объекты ссылаются на связанные объекты по идентификатору: у карточки есть 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, у которого есть области import:write и cards:read.
Событие старше 30 дней и событие тестовой доставки раскрываются как null.
expand[] только добавляет данные в ответ и никогда не меняет того, что делает запрос.