Gerelateerde objecten uitvouwen

Objecten verwijzen met een ID naar gerelateerde objecten: een kaart heeft owner_id en collection_id. Heb je het gerelateerde object zelf nodig, dan hoef je geen tweede request te sturen. Vraag het op met expand[] en het komt in dezelfde response mee, in 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"}
  }
}

Het voorbeeld is ingekort: een uitgevouwen object heeft alle velden van zijn eigen leesbewerking. De ID-velden blijven waar ze zijn, dus code die expand[] niet gebruikt, krijgt dezelfde response als voorheen.

Deze bewerkingen vouwen gerelateerde objecten uit. Een pad met een punt vouwt een koppeling van het uitgevouwen object uit: collection.default_owner is bijvoorbeeld de standaardeigenaar van de collectie van de kaart.

Bewerking	Paden
`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`

Elke koppeling komt in de vorm van de bewerking die het gerelateerde object leest:

Koppeling	Wat er in `expanded` komt
`collection`	De collectie, zoals in `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	De gebruiker, zoals in `GET /v1/users`: de volledige rij voor een aanroeper die gebruikers mag beheren, de beknopte rij (`brief=true`, alleen actieve gebruikers) voor andere aanroepers. `verifiers` is een lijst in de volgorde van `verifier_ids`.
`folders`	De mappen van de kaart in zijn collectie die de aanroeper kan zien, zoals in `GET /v1/folders/{folder_id}` zonder `path`.
`card`	De kaart, als item van `GET /v1/cards`.
`event`	Het event, zoals in `GET /v1/webhook-events/{event_id}`.

In lijsten

Begin het pad bij een lijst met data.: het geldt dan voor elk item van de pagina. Dat werkt hetzelfde voor een lijst die een array teruggeeft, zoals GET /v1/cards, en voor een lijst die haar items in een veld bewaart, zoals jobs van GET /v1/jobs of items van het leveringslog.

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 laadt elke koppeling voor de hele pagina in één keer, dus het uitvouwen in een lijst kost ongeveer evenveel als één extra request, niet één per item. De cursor van de volgende pagina hangt niet af van expand[], dus op de volgende pagina kun je om andere koppelingen vragen.

Regels

Maximaal 10 paden per request, elk maximaal 2 segmenten diep: data.owner in een lijst, collection.default_owner op een object.
Een onbekend pad, meer dan 10 paden of een pad dieper dan 2 segmenten geeft 400 met de code api.expand_invalid. details.path noemt het pad en details.reason zegt wat er mis is: unknown_path, too_deep of too_many_paths.
Een gerelateerd object wordt alleen uitgevouwen voor een aanroeper die het met een eigen request zou kunnen lezen. De sleutel heeft de scope van die bewerking nodig: cards:read voor kaarten, collecties en mappen, users:read voor gebruikers, webhooks:manage voor events. Het object moet ook zichtbaar zijn voor de aanroeper, bijvoorbeeld binnen de collecties van een sleutel die tot een deel van de collecties is beperkt. Anders wordt de koppeling uitgevouwen als null, en in verifiers staat null op de plaats van de gebruiker. De ID ervan wordt nog steeds teruggegeven. folders noemt alleen de mappen die de aanroeper kan zien.
Een bronsleutel leest geen kaarten, dus daarmee is card van een document altijd null. Wil je de kaart, roep de push-API dan aan met een API-sleutel die de scopes import:write en cards:read heeft.
Een event ouder dan 30 dagen en het event van een testlevering worden uitgevouwen als null.
expand[] voegt alleen gegevens aan de response toe. Het verandert nooit wat het request doet.