Rozbalenie súvisiacich objektov

Objekty odkazujú na súvisiace objekty cez ID: karta má owner_id a collection_id. Keď potrebujete samotný súvisiaci objekt, nemusíte posielať druhú požiadavku. Vyžiadajte si ho cez expand[] a príde v tej istej odpovedi, v poli 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"}
  }
}

Príklad je skrátený: rozbalený objekt má všetky polia vlastnej operácie čítania. Polia s ID zostávajú na svojom mieste, takže kód, ktorý expand[] nepoužíva, dostane rovnakú odpoveď ako predtým.

Súvisiace objekty rozbaľujú tieto operácie. Cesta s bodkou rozbalí odkaz rozbaleného objektu, napríklad collection.default_owner je predvolený vlastník kolekcie karty.

Operácia	Cesty
`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`

Každý odkaz prichádza v tvare operácie, ktorá súvisiaci objekt číta:

Odkaz	Čo príde v `expanded`
`collection`	Kolekcia ako v `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Používateľ ako v `GET /v1/users`: úplný riadok pre volajúceho, ktorý smie spravovať používateľov, skrátený riadok (`brief=true`, len aktívni používatelia) pre ostatných volajúcich. `verifiers` je zoznam v poradí `verifier_ids`.
`folders`	Priečinky karty v jej kolekcii, ktoré volajúci vidí, ako v `GET /v1/folders/{folder_id}` bez `path`.
`card`	Karta ako položka `GET /v1/cards`.
`event`	Udalosť ako v `GET /v1/webhook-events/{event_id}`.

V zoznamoch

Pri zozname začnite cestu predponou data.: platí potom pre každú položku stránky. Rovnako to platí pre zoznam, ktorý vracia pole, napríklad GET /v1/cards, aj pre zoznam, ktorý má položky v poli objektu, napríklad jobs v GET /v1/jobs alebo items v logu doručení.

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 načíta každý odkaz pre celú stránku naraz, takže rozbalenie v zozname stojí približne toľko ako jedna požiadavka navyše, nie jedna za každú položku. Kurzor ďalšej stránky nezávisí od expand[], takže na ďalšej stránke si môžete vyžiadať iné odkazy.

Pravidlá

Najviac 10 ciest v jednej požiadavke, každá najviac s 2 segmentmi: data.owner v zozname, collection.default_owner pri objekte.
Neznáma cesta, viac ako 10 ciest alebo cesta s viac ako 2 segmentmi vráti 400 s kódom api.expand_invalid. details.path uvádza cestu a details.reason hovorí, čo je zle: unknown_path, too_deep alebo too_many_paths.
Súvisiaci objekt sa rozbalí len pre volajúceho, ktorý by ho mohol prečítať vlastnou požiadavkou. Kľúč potrebuje rozsah tejto operácie: cards:read pre karty, kolekcie a priečinky, users:read pre používateľov, webhooks:manage pre udalosti. Objekt musí byť pre volajúceho aj viditeľný, napríklad v kolekciách kľúča, ktorý je obmedzený na niektoré kolekcie. Inak sa odkaz rozbalí ako null a vo verifiers je na mieste používateľa null. Jeho ID sa vráti aj tak. folders uvádza len priečinky, ktoré volajúci vidí.
Kľúč vlastného zdroja karty nečíta, preto je s ním card dokumentu vždy null. Ak chcete získať kartu, volajte API push s kľúčom API, ktorý má rozsahy import:write a cards:read.
Udalosť staršia ako 30 dní a udalosť testovacieho doručenia sa rozbalia ako null.
expand[] do odpovede len pridáva údaje. Nikdy nemení to, čo požiadavka vykoná.