Проширивање повезаних објеката

Објекти упућују на повезане објекте преко идентификатора: картица има 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. Његов ID се и даље враћа. folders наводи само фолдере које позивалац може да види.
Кључ сопственог извора не чита картице, па је са њим card документа увек null. Да бисте добили картицу, позовите API за слање (push) са API кључем који има опсеге import:write и cards:read.
Догађај старији од 30 дана и догађај пробне испоруке проширују се као null.
expand[] само додаје податке у одговор. Никада не мења оно што захтев ради.