Extinderea obiectelor asociate

Obiectele fac trimitere la obiectele asociate prin identificator: o fișă are owner_id și collection_id. Când aveți nevoie de obiectul asociat însuși, nu este necesară o a doua cerere. Cereți-l cu expand[] și va veni în același răspuns, în interiorul 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"}
  }
}

Exemplul este prescurtat: un obiect extins are toate câmpurile operației proprii de citire. Câmpurile cu identificatori rămân la locul lor, așa că un cod care nu folosește expand[] primește același răspuns ca înainte.

Aceste operații extind obiectele asociate. O cale cu punct extinde o legătură a obiectului extins, de exemplu collection.default_owner este responsabilul implicit al colecției fișei.

Operație	Că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`

Fiecare legătură vine în forma operației care citește obiectul asociat:

Legătură	Ce vine în `expanded`
`collection`	Colecția, ca în `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Utilizatorul, ca în `GET /v1/users`: rândul complet pentru cineva care poate gestiona utilizatorii, rândul scurt (`brief=true`, doar utilizatorii activi) pentru ceilalți. `verifiers` este o listă în ordinea din `verifier_ids`.
`folders`	Dosarele fișei din colecția ei pe care le poate vedea cel care face cererea, ca în `GET /v1/folders/{folder_id}` fără `path`.
`card`	Fișa, ca element al `GET /v1/cards`.
`event`	Evenimentul, ca în `GET /v1/webhook-events/{event_id}`.

În liste

Pentru o listă, începeți calea cu data.: ea se aplică fiecărui element al paginii. La fel este și pentru o listă care returnează un tablou, de exemplu GET /v1/cards, și pentru o listă care își păstrează elementele într-un câmp, de exemplu jobs din GET /v1/jobs sau items din jurnalul livrărilor.

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 încarcă dintr-odată fiecare legătură pentru întreaga pagină, așa că extinderea unei liste costă cam cât o singură cerere în plus, nu câte una pentru fiecare element. Cursorul paginii următoare nu depinde de expand[], așa că pe pagina următoare puteți cere alte legături.

Reguli

Cel mult 10 căi pe cerere, fiecare cu o adâncime de cel mult 2 segmente: data.owner într-o listă, collection.default_owner la un obiect.
O cale necunoscută, mai mult de 10 căi sau o cale mai adâncă de 2 segmente returnează 400 cu codul api.expand_invalid. details.path numește calea, iar details.reason spune ce este greșit: unknown_path, too_deep sau too_many_paths.
Un obiect asociat este extins doar pentru cineva care l-ar putea citi cu o cerere proprie. Cheia are nevoie de domeniul acelei operații: cards:read pentru fișe, colecții și dosare, users:read pentru utilizatori, webhooks:manage pentru evenimente. Obiectul trebuie să fie și vizibil pentru cel care face cererea, de exemplu în colecțiile unei chei limitate la anumite colecții. Altfel, legătura este extinsă ca null, iar în verifiers utilizatorul este null în locul lui. Identificatorul lui este returnat în continuare. folders enumeră doar dosarele pe care cel care face cererea le poate vedea.
O cheie de sursă personalizată nu citește fișe, așa că, folosind-o, card al unui document este mereu null. Pentru a obține fișa, apelați API-ul de trimitere (push) cu o cheie API care are domeniile import:write și cards:read.
Un eveniment mai vechi de 30 de zile și evenimentul unei livrări de test sunt extinse ca null.
expand[] doar adaugă date în răspuns. Nu schimbă niciodată ce face cererea.