Expansió d’objectes relacionats

Els objectes fan referència als objectes relacionats per ID: una entrada té owner_id i collection_id. Quan necessiteu l’objecte relacionat en si, no cal fer una segona sol·licitud. Demaneu-lo amb expand[] i arribarà a la mateixa resposta, dins d’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"}
  }
}

L’exemple està escurçat: un objecte expandit té tots els camps de la seva pròpia operació de lectura. Els camps d’ID es queden on són, de manera que el codi que no fa servir expand[] veu la mateixa resposta que abans.

Aquestes operacions expandeixen objectes relacionats. Un camí amb un punt expandeix una relació de l’objecte expandit; per exemple, collection.default_owner és el responsable per defecte de la col·lecció de l’entrada.

Cada relació arriba amb la forma de l’operació que llegeix l’objecte relacionat:

En llistes

En una llista, comenceu el camí amb data.: s’aplica a cada element de la pàgina. És igual per a una llista que retorna una matriu, com ara GET /v1/cards, i per a una llista que desa els elements en un camp, com ara jobs de GET /v1/jobs o items del registre de lliuraments.

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 carrega cada relació alhora per a tota la pàgina, de manera que expandir una llista costa aproximadament el mateix que una sol·licitud addicional, no una per element. El cursor de la pàgina següent no depèn d’expand[], de manera que a la pàgina següent podeu demanar altres relacions.

Regles

• Fins a 10 camins per sol·licitud, cadascun amb un màxim de 2 segments de profunditat: data.owner en una llista, collection.default_owner en un objecte.
• Un camí desconegut, més de 10 camins o un camí de més de 2 segments retorna 400 amb el codi api.expand_invalid. details.path indica el camí i details.reason diu què hi falla: unknown_path, too_deep o too_many_paths.
• Un objecte relacionat només s’expandeix per a qui el podria llegir amb la seva pròpia sol·licitud. La clau necessita l’àmbit d’aquella operació: cards:read per a entrades, col·leccions i carpetes, users:read per a usuaris, webhooks:manage per a esdeveniments. L’objecte també ha de ser visible per a qui fa la crida; per exemple, ha de ser dins de les col·leccions d’una clau limitada a algunes col·leccions. Si no, la relació s’expandeix com a null, i a verifiers l’usuari és null al seu lloc. El seu ID es continua retornant. folders només llista les carpetes que pot veure qui fa la crida.
• Una clau de font personalitzada no llegeix entrades, de manera que amb aquesta clau el card d’un document sempre és null. Per obtenir l’entrada, crideu l’API d’enviament amb una clau d’API que tingui els àmbits import:write i cards:read.
• Un esdeveniment de fa més de 30 dies i l’esdeveniment d’un lliurament de prova s’expandeixen com a null.
• expand[] només afegeix dades a la resposta. No canvia mai el que fa la sol·licitud.