Expandera relaterade objekt

Objekt hänvisar till relaterade objekt med id: ett kort har owner_id och collection_id. När du behöver själva det relaterade objektet behöver du inte göra ett andra anrop. Be om det med expand[], så kommer det i samma svar, inuti 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"}
  }
}

Exemplet är förkortat: ett expanderat objekt har alla fält från sin egen läsåtgärd. Id-fälten står kvar där de är, så kod som inte använder expand[] får samma svar som tidigare.

De här åtgärderna expanderar relaterade objekt. En sökväg med en punkt expanderar en länk i det expanderade objektet, till exempel är collection.default_owner standardansvarig för kortets samling.

Åtgärd	Sökvägar
`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`

Varje länk kommer i samma form som i den åtgärd som läser det relaterade objektet:

Länk	Vad som kommer i `expanded`
`collection`	Samlingen, som i `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Användaren, som i `GET /v1/users`: hela raden för en anropare som får hantera användare, den korta raden (`brief=true`, bara aktiva användare) för andra anropare. `verifiers` är en lista i samma ordning som `verifier_ids`.
`folders`	Kortets mappar i dess samling som anroparen kan se, som i `GET /v1/folders/{folder_id}` utan `path`.
`card`	Kortet, som ett element i `GET /v1/cards`.
`event`	Händelsen, som i `GET /v1/webhook-events/{event_id}`.

I listor

För en lista börjar du sökvägen med data.: den gäller då varje element på sidan. Det gäller både en lista som returnerar en array, till exempel GET /v1/cards, och en lista som har sina element i ett fält, till exempel jobs i GET /v1/jobs eller items i leveransloggen.

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 läser in varje länk för hela sidan på en gång, så att expandera en lista kostar ungefär lika mycket som ett extra anrop, inte ett per element. Markören för nästa sida beror inte på expand[], så du kan be om andra länkar på nästa sida.

Regler

Högst 10 sökvägar per anrop, var och en högst 2 segment djup: data.owner i en lista, collection.default_owner på ett objekt.
En okänd sökväg, fler än 10 sökvägar eller en sökväg djupare än 2 segment returnerar 400 med koden api.expand_invalid. details.path anger sökvägen och details.reason vad som är fel: unknown_path, too_deep eller too_many_paths.
Ett relaterat objekt expanderas bara för en anropare som kunde läsa det med ett eget anrop. Nyckeln behöver omfånget för den åtgärden: cards:read för kort, samlingar och mappar, users:read för användare, webhooks:manage för händelser. Objektet måste också vara synligt för anroparen, till exempel inom samlingarna för en nyckel som är begränsad till vissa samlingar. Annars expanderas länken som null, och i verifiers står null på användarens plats. Dess id returneras ändå. folders listar bara de mappar som anroparen kan se.
En källnyckel läser inte kort, så med den är card för ett dokument alltid null. Om du vill få kortet anropar du push-API:et med en API-nyckel som har omfången import:write och cards:read.
En händelse som är äldre än 30 dagar och händelsen för en testleverans expanderas som null.
expand[] lägger bara till data i svaret. Det ändrar aldrig vad anropet gör.