Rozbalení souvisejících objektů

Objekty odkazují na související objekty pomocí ID: karta má owner_id a collection_id. Když potřebujete samotný související objekt, nemusíte posílat druhý požadavek. Vyžádejte si ho pomocí expand[] a přijde ve stejné odpovědi, uvnitř 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"}
  }
}

Příklad je zkrácený: rozbalený objekt má všechna pole své vlastní operace čtení. Pole s ID zůstávají na svém místě, takže kód, který expand[] nepoužívá, vidí stejnou odpověď jako dřív.

Související objekty rozbalují tyto operace. Cesta s tečkou rozbalí odkaz rozbaleného objektu, například collection.default_owner je výchozí vlastník kolekce karty.

Operace	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 přichází v podobě, kterou vrací operace čtení souvisejícího objektu:

Odkaz	Co přijde v `expanded`
`collection`	Kolekce, jako v `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Uživatel, jako v `GET /v1/users`: úplný záznam pro volajícího, který smí spravovat uživatele, zkrácený záznam (`brief=true`, jen aktivní uživatelé) pro ostatní volající. `verifiers` je seznam v pořadí `verifier_ids`.
`folders`	Složky karty v její kolekci, které volající vidí, jako v `GET /v1/folders/{folder_id}` bez `path`.
`card`	Karta, jako položka `GET /v1/cards`.
`event`	Událost, jako v `GET /v1/webhook-events/{event_id}`.

V seznamech

U seznamu začněte cestu prefixem data.: platí pak pro každou položku stránky. Stejně je to u seznamu, který vrací pole, například GET /v1/cards, i u seznamu, který má položky v některém svém poli, například jobs u GET /v1/jobs nebo items u protokolu 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čte každý odkaz pro celou stránku najednou, takže rozbalení v seznamu stojí zhruba tolik co jeden požadavek navíc, ne jeden požadavek na každou položku. Kurzor další stránky na expand[] nezávisí, takže na další stránce si můžete vyžádat jiné odkazy.

Pravidla

Nejvýše 10 cest na požadavek, každá nejvýše ze 2 segmentů: data.owner v seznamu, collection.default_owner u objektu.
Neznámá cesta, více než 10 cest nebo cesta delší než 2 segmenty vrátí 400 s kódem api.expand_invalid. details.path uvádí cestu a details.reason říká, co je špatně: unknown_path, too_deep nebo too_many_paths.
Související objekt se rozbalí jen pro volajícího, který by ho mohl přečíst vlastním požadavkem. Klíč potřebuje rozsah příslušné operace: cards:read pro karty, kolekce a složky, users:read pro uživatele, webhooks:manage pro události. Objekt musí volající také vidět, například uvnitř kolekcí klíče, který je omezený jen na některé kolekce. Jinak se odkaz rozbalí jako null a ve verifiers stojí na místě uživatele null. Jeho ID se přesto vrací. folders uvádí jen složky, které volající vidí.
Klíč vlastního zdroje karty nečte, proto je s ním card dokumentu vždy null. Chcete-li kartu získat, volejte API push s klíčem API, který má rozsahy import:write a cards:read.
Událost starší než 30 dní a událost testovacího doručení se rozbalí jako null.
expand[] jen přidává data do odpovědi. Nikdy nemění, co požadavek dělá.