Espandere gli oggetti correlati

Gli oggetti fanno riferimento agli oggetti correlati tramite ID: una scheda ha owner_id e collection_id. Quando ti serve l’oggetto correlato vero e proprio, non devi fare una seconda richiesta. Chiedilo con expand[] e arriva nella stessa risposta, dentro 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’esempio è abbreviato: un oggetto espanso ha tutti i campi della sua operazione di lettura. I campi con gli ID restano dove sono, quindi il codice che non usa expand[] vede la stessa risposta di prima.

Queste operazioni espandono gli oggetti correlati. Un percorso con un punto espande un collegamento dell’oggetto espanso: per esempio collection.default_owner è il responsabile predefinito della raccolta della scheda.

Ogni collegamento arriva nella forma dell’operazione che legge l’oggetto correlato:

Negli elenchi

Per un elenco, inizia il percorso con data.: si applica a ogni elemento della pagina. Vale sia per un elenco che restituisce un array, come GET /v1/cards, sia per un elenco che tiene i suoi elementi in un campo, come jobs di GET /v1/jobs o items del registro delle consegne.

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 carica ogni collegamento per l’intera pagina in una volta, quindi espandere un elenco costa più o meno quanto una richiesta in più, non una per elemento. Il cursore della pagina successiva non dipende da expand[], quindi nella pagina successiva puoi chiedere altri collegamenti.

Regole

• Fino a 10 percorsi per richiesta, ciascuno con al massimo 2 segmenti di profondità: data.owner in un elenco, collection.default_owner su un oggetto.
• Un percorso sconosciuto, più di 10 percorsi o un percorso con più di 2 segmenti restituiscono 400 con il codice api.expand_invalid. details.path indica il percorso e details.reason dice cosa non va: unknown_path, too_deep o too_many_paths.
• Un oggetto correlato viene espanso solo se chi effettua la chiamata potrebbe leggerlo con una propria richiesta. La chiave ha bisogno dell’ambito di quell’operazione: cards:read per schede, raccolte e cartelle, users:read per gli utenti, webhooks:manage per gli eventi. L’oggetto deve anche essere visibile a chi effettua la chiamata, per esempio all’interno delle raccolte di una chiave limitata ad alcune raccolte. Altrimenti il collegamento viene espanso come null, e in verifiers al posto dell’utente c’è null. Il suo ID viene comunque restituito. folders elenca solo le cartelle che chi effettua la chiamata può vedere.
• Una chiave di fonte personalizzata non legge le schede, quindi con questa chiave card di un documento è sempre null. Per ottenere la scheda, chiama l’API di invio con una chiave API che abbia gli ambiti import:write e cards:read.
• Un evento più vecchio di 30 giorni e l’evento di una consegna di test vengono espansi come null.
• expand[] aggiunge solo dati alla risposta. Non cambia mai ciò che fa la richiesta.