Kapcsolódó objektumok kibontása

Az objektumok azonosítóval hivatkoznak a kapcsolódó objektumokra: a kártyának van owner_id és collection_id mezője. Ha magára a kapcsolódó objektumra van szükséged, nem kell második kérést küldened. Kérd az expand[] paraméterrel, és ugyanabban a válaszban, az expanded mezőben megkapod:

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"}
  }
}

A példa rövidített: a kibontott objektum a saját olvasási műveletének minden mezőjét tartalmazza. Az azonosítómezők a helyükön maradnak, így az expand[] paramétert nem használó kód ugyanazt a választ látja, mint korábban.

Az alábbi műveletek bontják ki a kapcsolódó objektumokat. A pontot tartalmazó útvonal a kibontott objektum egy kapcsolatát bontja ki, például a collection.default_owner a kártya gyűjteményének alapértelmezett felelőse.

Művelet	Útvonalak
`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`

Minden kapcsolat abban az alakban érkezik, ahogyan a kapcsolódó objektumot olvasó művelet visszaadja:

Kapcsolat	Mi kerül az `expanded` mezőbe
`collection`	A gyűjtemény, mint a `GET /v1/collections` válaszában.
`owner`, `verifiers`, `default_owner`	A felhasználó, mint a `GET /v1/users` válaszában: a felhasználók kezelésére jogosult hívónak a teljes sor, a többi hívónak a rövid sor (`brief=true`, csak aktív felhasználók). A `verifiers` lista a `verifier_ids` sorrendjét követi.
`folders`	A kártya gyűjteményén belüli, a hívó számára látható mappái, mint a `GET /v1/folders/{folder_id}` válaszában, `path` nélkül.
`card`	A kártya, a `GET /v1/cards` lista egy elemeként.
`event`	Az esemény, mint a `GET /v1/webhook-events/{event_id}` válaszában.

Listákban

Listánál az útvonalat kezdd data. előtaggal: ez az oldal minden elemére vonatkozik. Ugyanez érvényes a tömböt visszaadó listára, például a GET /v1/cards végpontra, és arra a listára is, amely egy mezőben tartja az elemeit, például a GET /v1/jobs válaszában a jobs vagy a kézbesítési naplóban az items mező.

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"

A Sursa minden kapcsolatot egyszerre tölt be az egész oldalra, így egy lista kibontása nagyjából annyiba kerül, mint egyetlen további kérés, nem pedig elemenként egy. A következő oldal kurzora nem függ az expand[] paramétertől, így a következő oldalon más kapcsolatokat is kérhetsz.

Szabályok

Kérésenként legfeljebb 10 útvonal, mindegyik legfeljebb 2 szegmensből áll: listában data.owner, objektumon collection.default_owner.
Ismeretlen útvonal, 10-nél több útvonal vagy 2 szegmensnél mélyebb útvonal esetén a válasz 400 az api.expand_invalid kóddal. A details.path megnevezi az útvonalat, a details.reason pedig megmondja, mi a hiba: unknown_path, too_deep vagy too_many_paths.
A kapcsolódó objektum csak akkor bomlik ki, ha a hívó saját kéréssel is elolvashatná. A kulcsnak rendelkeznie kell az adott művelet hatókörével: kártyákhoz, gyűjteményekhez és mappákhoz cards:read, felhasználókhoz users:read, eseményekhez webhooks:manage. Az objektumnak a hívó számára láthatónak is kell lennie, például egyes gyűjteményekre korlátozott kulcsnál ezeken a gyűjteményeken belül. Ellenkező esetben a kapcsolat null értékként bomlik ki, a verifiers listában pedig a felhasználó helyén null áll. Az azonosítója ilyenkor is megjelenik a válaszban. A folders csak a hívó számára látható mappákat sorolja fel.
Az egyéni forrás kulcsa nem olvas kártyákat, ezért vele egy dokumentum card mezője mindig null. A kártya lekéréséhez a küldési (push) API-t olyan API-kulccsal hívd, amelynek megvan az import:write és a cards:read hatóköre.
A 30 napnál régebbi esemény és a tesztkézbesítés eseménye null értékként bomlik ki.
Az expand[] csak adatot ad hozzá a válaszhoz. Soha nem változtatja meg, hogy mit csinál a kérés.