Proširivanje povezanih objekata

Objekti upućuju na povezane objekte putem ID-a: kartica ima owner_id i collection_id. Kad vam treba sam povezani objekt, ne morate slati drugi zahtjev. Zatražite ga pomoću expand[] i on stiže u istom odgovoru, unutar 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"}
  }
}

Primjer je skraćen: prošireni objekt ima sva polja vlastite operacije čitanja. Polja s ID-ovima ostaju gdje jesu, pa kod koji ne koristi expand[] vidi isti odgovor kao i prije.

Ove operacije proširuju povezane objekte. Putanja s točkom proširuje vezu proširenog objekta, primjerice collection.default_owner je zadani vlasnik zbirke kartice.

Operacija	Putanje
`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`

Svaka veza stiže u obliku operacije koja čita povezani objekt:

Veza	Što stiže u `expanded`
`collection`	Zbirka, kao u `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Korisnik, kao u `GET /v1/users`: puni redak za pozivatelja koji smije upravljati korisnicima, kratki redak (`brief=true`, samo aktivni korisnici) za ostale pozivatelje. `verifiers` je popis u redoslijedu `verifier_ids`.
`folders`	Mape kartice u njezinoj zbirci koje pozivatelj vidi, kao u `GET /v1/folders/{folder_id}` bez `path`.
`card`	Kartica, kao stavka `GET /v1/cards`.
`event`	Događaj, kao u `GET /v1/webhook-events/{event_id}`.

U popisima

Kod popisa putanju započnite s data.: tada se primjenjuje na svaku stavku stranice. Tako je i kod popisa koji vraća niz, kao što je GET /v1/cards, i kod popisa koji svoje stavke drži u polju, kao što je jobs u GET /v1/jobs ili items u zapisniku isporuka.

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 učitava svaku vezu za cijelu stranicu odjednom, pa proširivanje popisa stoji otprilike koliko i jedan dodatni zahtjev, a ne po jedan za svaku stavku. Kursor sljedeće stranice ne ovisi o expand[], pa na sljedećoj stranici možete zatražiti druge veze.

Pravila

Do 10 putanja po zahtjevu, svaka od najviše 2 segmenta: data.owner u popisu, collection.default_owner na objektu.
Nepoznata putanja, više od 10 putanja ili putanja dublja od 2 segmenta vraća 400 s kodom api.expand_invalid. details.path navodi putanju, a details.reason kaže što ne valja: unknown_path, too_deep ili too_many_paths.
Povezani objekt proširuje se samo za pozivatelja koji bi ga mogao pročitati vlastitim zahtjevom. Ključu treba opseg te operacije: cards:read za kartice, zbirke i mape, users:read za korisnike, webhooks:manage za događaje. Objekt također mora biti vidljiv pozivatelju, primjerice unutar zbirki ključa koji je ograničen na neke zbirke. Inače se veza proširuje kao null, a u verifiers je na mjestu korisnika null. Njegov se ID i dalje vraća. folders navodi samo mape koje pozivatelj vidi.
Ključ vlastitog izvora ne čita kartice, pa je s njim card dokumenta uvijek null. Da biste dobili karticu, pozovite API za slanje (push) API ključem koji ima opsege import:write i cards:read.
Događaj stariji od 30 dana i događaj probne isporuke proširuju se kao null.
expand[] samo dodaje podatke u odgovor. Nikada ne mijenja ono što zahtjev radi.