Udvidelse af relaterede objekter

Objekter henviser til relaterede objekter med id: Et kort har owner_id og collection_id. Når du har brug for selve det relaterede objekt, behøver du ikke sende endnu en anmodning. Bed om det med expand[], så kommer det med i samme svar, i 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"}
  }
}

Eksemplet er forkortet: Et udvidet objekt har alle felterne fra sin egen læseoperation. Id-felterne bliver, hvor de er, så kode, der ikke bruger expand[], får det samme svar som før.

Disse operationer udvider relaterede objekter. En sti med punktum udvider en relation i det udvidede objekt, fx er collection.default_owner standardejeren af kortets samling.

Operation	Stier
`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`

Hver relation kommer i samme form som i den operation, der læser det relaterede objekt:

Relation	Hvad der kommer i `expanded`
`collection`	Samlingen som i `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Brugeren som i `GET /v1/users`: den fulde række for en kaldende part, der må administrere brugere, og den korte række (`brief=true`, kun aktive brugere) for andre kaldende parter. `verifiers` er en liste i samme rækkefølge som `verifier_ids`.
`folders`	Kortets mapper i dets samling, som den kaldende part kan se, som i `GET /v1/folders/{folder_id}` uden `path`.
`card`	Kortet som et element i `GET /v1/cards`.
`event`	Hændelsen som i `GET /v1/webhook-events/{event_id}`.

I lister

For en liste begynder stien med data.: Den gælder for hvert element på siden. Det gælder både for en liste, der returnerer et array, fx GET /v1/cards, og for en liste, der har sine elementer i et felt, fx jobs i GET /v1/jobs eller items i leveringsloggen.

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 indlæser hver relation for hele siden på én gang, så udvidelse af en liste koster omtrent det samme som én ekstra anmodning, ikke én pr. element. Cursoren for næste side afhænger ikke af expand[], så du kan bede om andre relationer på næste side.

Regler

Op til 10 stier pr. anmodning, hver højst 2 segmenter dyb: data.owner i en liste, collection.default_owner på et objekt.
En ukendt sti, mere end 10 stier eller en sti, der er dybere end 2 segmenter, returnerer 400 med koden api.expand_invalid. details.path angiver stien, og details.reason fortæller, hvad der er galt: unknown_path, too_deep eller too_many_paths.
Et relateret objekt udvides kun for en kaldende part, der kunne læse det med sin egen anmodning. Nøglen skal have scopet for den pågældende operation: cards:read for kort, samlinger og mapper, users:read for brugere, webhooks:manage for hændelser. Objektet skal også være synligt for den kaldende part, fx inden for samlingerne for en nøgle, der er begrænset til bestemte samlinger. Ellers udvides relationen som null, og i verifiers står null på brugerens plads. Dets id returneres stadig. folders viser kun de mapper, som den kaldende part kan se.
En nøgle til en brugerdefineret kilde læser ikke kort, så med den er et dokuments card altid null. Vil du have kortet, skal du kalde push-API’et med en API-nøgle, der har scopes import:write og cards:read.
En hændelse, der er ældre end 30 dage, og hændelsen fra en testlevering udvides som null.
expand[] tilføjer kun data til svaret. Den ændrer aldrig, hvad anmodningen gør.