Expandir objetos relacionados

Los objetos hacen referencia a objetos relacionados mediante su ID: una tarjeta tiene owner_id y collection_id. Cuando necesite el propio objeto relacionado, no tiene que hacer una segunda solicitud. Pídalo con expand[] y llegará en la misma respuesta, dentro de 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"}
  }
}

El ejemplo está abreviado: un objeto expandido tiene todos los campos de su propia operación de lectura. Los campos de ID se quedan donde están, así que el código que no usa expand[] recibe la misma respuesta que antes.

Estas operaciones expanden objetos relacionados. Una ruta con punto expande una relación del objeto expandido; por ejemplo, collection.default_owner es el responsable predeterminado de la colección de la tarjeta.

Operación	Rutas
`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`

Cada relación llega con la forma de la operación que lee el objeto relacionado:

Relación	Qué llega en `expanded`
`collection`	La colección, como en `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	El usuario, como en `GET /v1/users`: la fila completa para quien llama a la API y puede gestionar usuarios, y la fila breve (`brief=true`, solo usuarios activos) para los demás. `verifiers` es una lista en el orden de `verifier_ids`.
`folders`	Las carpetas de la tarjeta en su colección que puede ver quien llama a la API, como en `GET /v1/folders/{folder_id}` sin `path`.
`card`	La tarjeta, como un elemento de `GET /v1/cards`.
`event`	El evento, como en `GET /v1/webhook-events/{event_id}`.

En las listas

En una lista, empiece la ruta con data.: se aplica a todos los elementos de la página. Es igual para una lista que devuelve un array, como GET /v1/cards, y para una lista que guarda sus elementos en un campo, como jobs de GET /v1/jobs o items del registro de entregas.

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 carga cada relación de toda la página a la vez, de modo que expandir una lista cuesta más o menos lo mismo que una solicitud adicional, no una por elemento. El cursor de la página siguiente no depende de expand[], así que en la página siguiente puede pedir otras relaciones.

Reglas

Hasta 10 rutas por solicitud, cada una con un máximo de 2 segmentos de profundidad: data.owner en una lista, collection.default_owner en un objeto.
Una ruta desconocida, más de 10 rutas o una ruta con más de 2 segmentos devuelven 400 con el código api.expand_invalid. details.path indica la ruta y details.reason dice qué falla: unknown_path, too_deep o too_many_paths.
Un objeto relacionado solo se expande para quien podría leerlo con su propia solicitud. La clave necesita el ámbito de esa operación: cards:read para tarjetas, colecciones y carpetas, users:read para usuarios, webhooks:manage para eventos. Además, el objeto tiene que ser visible para quien llama a la API, por ejemplo, estar dentro de las colecciones de una clave limitada a algunas colecciones. Si no, la relación se expande como null, y en verifiers aparece null en el lugar del usuario. Su ID se sigue devolviendo. folders solo enumera las carpetas que puede ver quien llama a la API.
Una clave de fuente personalizada no lee tarjetas, así que con ella card de un documento siempre es null. Para obtener la tarjeta, llame a la API de envío con una clave de API que tenga los ámbitos import:write y cards:read.
Un evento de hace más de 30 días y el evento de una entrega de prueba se expanden como null.
expand[] solo añade datos a la respuesta. Nunca cambia lo que hace la solicitud.