Saistīto objektu izvēršana

Objekti uz saistītajiem objektiem atsaucas ar ID: kartītei ir owner_id un collection_id. Ja jums vajadzīgs pats saistītais objekts, otrs pieprasījums nav jāsūta. Pieprasiet to ar expand[], un tas tiks atgriezts tajā pašā atbildē, laukā 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"}
  }
}

Piemērs ir saīsināts: izvērstajam objektam ir visi lauki, ko atgriež tā lasīšanas operācija. ID lauki paliek savās vietās, tāpēc kods, kas neizmanto expand[], saņem tādu pašu atbildi kā iepriekš.

Saistītos objektus izvērš šīs operācijas. Ceļš ar punktu izvērš izvērstā objekta saiti, piemēram, collection.default_owner ir kartītes kolekcijas noklusējuma atbildīgā persona.

Operācija	Ceļi
`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`

Katra saite tiek atgriezta tādā formā, kādā saistīto objektu atgriež tā lasīšanas operācija:

Saite	Kas tiek atgriezts laukā `expanded`
`collection`	Kolekcija, kā operācijā `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Lietotājs, kā operācijā `GET /v1/users`: pilns ieraksts izsaucējam, kurš drīkst pārvaldīt lietotājus, īsais ieraksts (`brief=true`, tikai aktīvi lietotāji) pārējiem izsaucējiem. `verifiers` ir saraksts `verifier_ids` secībā.
`folders`	Kartītes mapes tās kolekcijā, kuras izsaucējs var redzēt, kā operācijā `GET /v1/folders/{folder_id}` bez `path`.
`card`	Kartīte, kā `GET /v1/cards` saraksta elements.
`event`	Notikums, kā operācijā `GET /v1/webhook-events/{event_id}`.

Sarakstos

Sarakstam ceļu sāciet ar data.: tas attiecas uz katru lapas elementu. Tas pats attiecas gan uz sarakstu, kas atgriež masīvu, piemēram, GET /v1/cards, gan uz sarakstu, kas elementus glabā laukā, piemēram, jobs operācijā GET /v1/jobs vai items piegāžu žurnālā.

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 ielādē katru saiti visai lapai uzreiz, tāpēc saraksta izvēršana izmaksā aptuveni tikpat, cik viens papildu pieprasījums, nevis pa vienam pieprasījumam katram elementam. Nākamās lapas kursors nav atkarīgs no expand[], tāpēc nākamajā lapā varat pieprasīt citas saites.

Noteikumi

Vienā pieprasījumā – līdz 10 ceļiem, katrs ne vairāk par 2 segmentiem: data.owner sarakstā, collection.default_owner objektam.
Nezināms ceļš, vairāk nekā 10 ceļi vai ceļš, kas garāks par 2 segmentiem, atgriež 400 ar kodu api.expand_invalid. details.path norāda ceļu, bet details.reason – kas nav kārtībā: unknown_path, too_deep vai too_many_paths.
Saistītais objekts tiek izvērsts tikai izsaucējam, kurš to varētu nolasīt ar atsevišķu pieprasījumu. Atslēgai vajadzīgs šīs operācijas tvērums: cards:read kartītēm, kolekcijām un mapēm, users:read lietotājiem, webhooks:manage notikumiem. Objektam arī jābūt redzamam izsaucējam, piemēram, kolekcijās, ar kurām ierobežota atslēga. Pretējā gadījumā saite tiek izvērsta kā null, bet verifiers sarakstā attiecīgā lietotāja vietā ir null. Tā ID joprojām tiek atgriezts. folders uzskaita tikai tās mapes, kuras izsaucējs var redzēt.
Pielāgotā avota atslēga nelasa kartītes, tāpēc ar to dokumenta card vienmēr ir null. Lai iegūtu kartīti, izsauciet push API ar API atslēgu, kurai ir tvērumi import:write un cards:read.
Notikums, kas vecāks par 30 dienām, un testa piegādes notikums tiek izvērsti kā null.
expand[] tikai pievieno atbildei datus. Tas nekad nemaina to, ko pieprasījums dara.