Utvide relaterte objekter

Objekter viser til relaterte objekter med ID: Et kort har owner_id og collection_id. Når du trenger selve det relaterte objektet, trenger du ikke sende en forespørsel til. Be om det med expand[], så kommer det i samme svar, inne 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"}
  }
}

Eksempelet er forkortet: Et utvidet objekt har alle feltene fra sin egen leseoperasjon. ID-feltene blir stående der de er, så kode som ikke bruker expand[], får det samme svaret som før.

Disse operasjonene utvider relaterte objekter. En bane med punktum utvider en relasjon i det utvidede objektet, for eksempel er collection.default_owner standard ansvarlig for samlingen kortet ligger i.

Operasjon	Baner
`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 relasjon kommer i samme form som i operasjonen som leser det relaterte objektet:

Relasjon	Hva som kommer i `expanded`
`collection`	Samlingen, som i `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Brukeren, som i `GET /v1/users`: hele raden når den som kaller, har lov til å administrere brukere, ellers den korte raden (`brief=true`, bare aktive brukere). `verifiers` er en liste i samme rekkefølge som `verifier_ids`.
`folders`	Kortets mapper i samlingen, bare de som den som kaller, kan se, som i `GET /v1/folders/{folder_id}` uten `path`.
`card`	Kortet, som et element i `GET /v1/cards`.
`event`	Hendelsen, som i `GET /v1/webhook-events/{event_id}`.

I lister

For en liste starter du banen med data.: Da gjelder den for hvert element på siden. Det samme gjelder for en liste som returnerer et array, som GET /v1/cards, og for en liste som har elementene i et felt, som 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 laster inn hver relasjon for hele siden på én gang, så å utvide en liste koster omtrent like mye som én ekstra forespørsel, ikke én per element. Cursoren til neste side avhenger ikke av expand[], så du kan be om andre relasjoner på neste side.

Regler

Opptil 10 baner per forespørsel, hver med høyst 2 ledd: data.owner i en liste, collection.default_owner på et objekt.
En ukjent bane, mer enn 10 baner eller en bane med mer enn 2 ledd returnerer 400 med koden api.expand_invalid. details.path angir banen, og details.reason forteller hva som er feil: unknown_path, too_deep eller too_many_paths.
Et relatert objekt utvides bare for en som kunne ha lest det med en egen forespørsel. Nøkkelen trenger scopet til den operasjonen: cards:read for kort, samlinger og mapper, users:read for brukere, webhooks:manage for hendelser. Objektet må også være synlig for den som kaller, for eksempel innenfor samlingene til en nøkkel som er begrenset til noen samlinger. Ellers utvides relasjonen som null, og i verifiers står null i stedet for brukeren. ID-en returneres likevel. folders viser bare mappene som den som kaller, kan se.
En kildenøkkel leser ikke kort, så med den er card for et dokument alltid null. For å få kortet kaller du push-API-et med en API-nøkkel som har scopene import:write og cards:read.
En hendelse som er eldre enn 30 dager, og hendelsen til en testleveranse utvides som null.
expand[] legger bare til data i svaret. Det endrer aldri hva forespørselen gjør.