Verknüpfte Objekte erweitern

Objekte verweisen über IDs auf verknüpfte Objekte: Eine Karte hat owner_id und collection_id. Wenn Sie das verknüpfte Objekt selbst brauchen, müssen Sie keine zweite Anfrage stellen. Fordern Sie es mit expand[] an, und es kommt in derselben Antwort, innerhalb von 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"}
  }
}

Das Beispiel ist gekürzt: Ein erweitertes Objekt hat alle Felder seiner eigenen Leseoperation. Die ID-Felder bleiben, wo sie sind, sodass Code, der expand[] nicht verwendet, dieselbe Antwort sieht wie bisher.

Diese Operationen erweitern verknüpfte Objekte. Ein Pfad mit Punkt erweitert eine Verknüpfung des erweiterten Objekts, zum Beispiel ist collection.default_owner die standardmäßig verantwortliche Person der Sammlung der Karte.

Jede Verknüpfung kommt in der Form der Operation, die das verknüpfte Objekt liest:

In Listen

Bei einer Liste beginnen Sie den Pfad mit data.: Er gilt dann für jedes Element der Seite. Das gilt gleichermaßen für eine Liste, die ein Array zurückgibt, etwa GET /v1/cards, und für eine Liste, die ihre Elemente in einem Feld hält, etwa jobs von GET /v1/jobs oder items des Zustellprotokolls.

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ädt jede Verknüpfung für die ganze Seite auf einmal. Eine erweiterte Liste kostet daher etwa so viel wie eine zusätzliche Anfrage, nicht eine pro Element. Der Cursor der nächsten Seite hängt nicht von expand[] ab, sodass Sie auf der nächsten Seite andere Verknüpfungen anfordern können.

Regeln

• Bis zu 10 Pfade pro Anfrage, jeder höchstens 2 Segmente tief: data.owner in einer Liste, collection.default_owner an einem Objekt.
• Ein unbekannter Pfad, mehr als 10 Pfade oder ein Pfad, der tiefer als 2 Segmente reicht, ergibt 400 mit dem Code api.expand_invalid. details.path nennt den Pfad, und details.reason sagt, was falsch ist: unknown_path, too_deep oder too_many_paths.
• Ein verknüpftes Objekt wird nur für einen Aufrufer erweitert, der es mit einer eigenen Anfrage lesen könnte. Der Schlüssel braucht den Scope dieser Operation: cards:read für Karten, Sammlungen und Ordner, users:read für Benutzer, webhooks:manage für Ereignisse. Das Objekt muss für den Aufrufer außerdem sichtbar sein, zum Beispiel innerhalb der Sammlungen eines Schlüssels, der auf einige Sammlungen beschränkt ist. Andernfalls wird die Verknüpfung als null erweitert, und in verifiers steht an der Stelle des Benutzers null. Die ID des Objekts wird trotzdem zurückgegeben. folders listet nur die Ordner auf, die der Aufrufer sehen kann.
• Ein Schlüssel einer benutzerdefinierten Quelle liest keine Karten, daher ist card eines Dokuments mit ihm immer null. Um die Karte zu erhalten, rufen Sie die Push-API mit einem API-Schlüssel auf, der die Scopes import:write und cards:read hat.
• Ein Ereignis, das älter als 30 Tage ist, und das Ereignis einer Testzustellung werden als null erweitert.
• expand[] fügt der Antwort nur Daten hinzu. Es ändert nie, was die Anfrage bewirkt.