Liittyvien objektien laajentaminen

Objektit viittaavat liittyviin objekteihin tunnuksilla: kortilla on owner_id ja collection_id. Kun tarvitset itse liittyvän objektin, sinun ei tarvitse tehdä toista pyyntöä. Pyydä sitä expand[]-parametrilla, niin se tulee samassa vastauksessa expanded-kentän sisällä:

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

Esimerkki on lyhennetty: laajennetulla objektilla on kaikki sen oman lukutoiminnon kentät. Tunnuskentät pysyvät paikoillaan, joten koodi, joka ei käytä expand[]-parametria, näkee saman vastauksen kuin ennenkin.

Seuraavat toiminnot laajentavat liittyviä objekteja. Pisteen sisältävä polku laajentaa laajennetun objektin viittauksen: esimerkiksi collection.default_owner on kortin kokoelman oletusomistaja.

Toiminto	Polut
`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`

Kukin viittaus tulee siinä muodossa, jossa liittyvän objektin lukeva toiminto sen palauttaa:

Viittaus	Mitä `expanded`-kenttään tulee
`collection`	Kokoelma, kuten `GET /v1/collections` -listassa.
`owner`, `verifiers`, `default_owner`	Käyttäjä, kuten `GET /v1/users` -listassa: täysi rivi kutsujalle, joka saa hallita käyttäjiä, ja suppea rivi (`brief=true`, vain aktiiviset käyttäjät) muille kutsujille. `verifiers` on lista `verifier_ids`-kentän järjestyksessä.
`folders`	Ne kortin kansiot sen kokoelmassa, jotka kutsuja näkee, kuten `GET /v1/folders/{folder_id}` -pyynnössä ilman `path`-parametria.
`card`	Kortti, kuten `GET /v1/cards` -listan kohde.
`event`	Tapahtuma, kuten `GET /v1/webhook-events/{event_id}` -pyynnössä.

Listoissa

Aloita listan polku merkkijonolla data.: silloin se koskee sivun jokaista kohdetta. Sama pätee listaan, joka palauttaa taulukon, kuten GET /v1/cards, ja listaan, joka pitää kohteensa kentässä, kuten GET /v1/jobs -listan jobs-kenttä tai toimituslokin items-kenttä.

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 lataa kunkin viittauksen koko sivulle kerralla, joten listan laajentaminen maksaa suunnilleen yhden lisäpyynnön verran eikä yhtä pyyntöä kohdetta kohden. Seuraavan sivun kursori ei riipu expand[]-parametrista, joten seuraavalla sivulla voit pyytää muita viittauksia.

Säännöt

Enintään 10 polkua pyyntöä kohden, kukin enintään 2 osan syvyinen: data.owner listassa, collection.default_owner objektissa.
Tuntematon polku, yli 10 polkua tai yli 2 osan syvyinen polku palauttaa 400-vastauksen ja koodin api.expand_invalid. details.path nimeää polun, ja details.reason kertoo, mikä on vialla: unknown_path, too_deep tai too_many_paths.
Liittyvä objekti laajennetaan vain kutsujalle, joka voisi lukea sen omalla pyynnöllään. Avaimella täytyy olla kyseisen toiminnon käyttöalue: cards:read korteille, kokoelmille ja kansioille, users:read käyttäjille, webhooks:manage tapahtumille. Objektin täytyy myös näkyä kutsujalle, esimerkiksi tiettyihin kokoelmiin rajatun avaimen kokoelmien sisällä. Muuten viittaus laajennetaan arvoksi null, ja verifiers-listassa käyttäjän paikalla on null. Sen tunnus palautetaan silti. folders listaa vain kansiot, jotka kutsuja näkee.
Mukautetun lähteen avain ei lue kortteja, joten sitä käytettäessä asiakirjan card on aina null. Jos tarvitset kortin, kutsu push-API:a API-avaimella, jolla on käyttöalueet import:write ja cards:read.
Yli 30 päivää vanha tapahtuma ja testitoimituksen tapahtuma laajennetaan arvoksi null.
expand[] vain lisää tietoja vastaukseen. Se ei koskaan muuta sitä, mitä pyyntö tekee.