Seotud objektide laiendamine

Objektid viitavad seotud objektidele ID kaudu: kaardil on owner_id ja collection_id. Kui vajate seotud objekti ennast, ei pea te tegema teist päringut. Küsige seda parameetriga expand[] ja see tuleb samas vastuses väljal 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"}
  }
}

Näide on lühendatud: laiendatud objektil on kõik selle enda lugemistoimingu väljad. ID-väljad jäävad oma kohale, seega näeb kood, mis parameetrit expand[] ei kasuta, sama vastust nagu varem.

Need toimingud laiendavad seotud objekte. Punktiga tee laiendab laiendatud objekti viidet, näiteks collection.default_owner on kaardi kogu vaikimisi vastutaja.

Toiming	Teed
`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`

Iga viide tuleb selle toimingu kujul, mis seotud objekti loeb:

Viide	Mis tuleb väljale `expanded`
`collection`	Kogu, nagu lõpp-punktis `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Kasutaja, nagu lõpp-punktis `GET /v1/users`: täielik rida päringu tegijale, kes tohib kasutajaid hallata, ja lühirida (`brief=true`, ainult aktiivsed kasutajad) teistele päringu tegijatele. `verifiers` on loend välja `verifier_ids` järjekorras.
`folders`	Kaardi need kaustad selle kogus, mida päringu tegija näeb, nagu lõpp-punktis `GET /v1/folders/{folder_id}` ilma parameetrita `path`.
`card`	Kaart, nagu lõpp-punkti `GET /v1/cards` loendi element.
`event`	Sündmus, nagu lõpp-punktis `GET /v1/webhook-events/{event_id}`.

Loendites

Loendi puhul alustage teed eesliitega data.: see kehtib lehe iga elemendi kohta. Nii on see nii loendis, mis tagastab massiivi, näiteks GET /v1/cards, kui ka loendis, mis hoiab elemente väljal, näiteks lõpp-punkti GET /v1/jobs väli jobs või edastuslogi väli items.

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 laadib iga viite kogu lehe jaoks korraga, seega maksab loendi laiendamine umbes sama palju kui üks lisapäring, mitte üks päring iga elemendi kohta. Järgmise lehe kursor ei sõltu parameetrist expand[], seega võite järgmisel lehel küsida teisi viiteid.

Reeglid

Kuni 10 teed päringu kohta, igaüks kuni 2 lõiku sügav: loendis data.owner, objektil collection.default_owner.
Kui tee on tundmatu, teid on üle 10 või tee on sügavam kui 2 lõiku, on vastus 400 koodiga api.expand_invalid. details.path nimetab tee ja details.reason ütleb, mis on valesti: unknown_path, too_deep või too_many_paths.
Seotud objekt laiendatakse ainult päringu tegijale, kes saaks seda lugeda oma päringuga. Võtmel peab olema selle toimingu ulatus: kaartide, kogude ja kaustade jaoks cards:read, kasutajate jaoks users:read, sündmuste jaoks webhooks:manage. Objekt peab päringu tegijale olema ka nähtav, näiteks teatud kogudega piiratud võtme puhul nende kogude sees. Vastasel juhul laiendatakse viide väärtusena null ja loendis verifiers on kasutaja asemel null. Selle ID tagastatakse siiski. folders loetleb ainult kaustad, mida päringu tegija näeb.
Kohandatud allika võti ei loe kaarte, seega on dokumendi väli card sellega alati null. Kaardi saamiseks kutsuge push-API-t API-võtmega, millel on ulatused import:write ja cards:read.
Üle 30 päeva vanune sündmus ja testedastuse sündmus laiendatakse väärtusena null.
Parameeter expand[] ainult lisab vastusesse andmeid. See ei muuda kunagi seda, mida päring teeb.