Rozwijanie powiązanych obiektów

Obiekty odwołują się do powiązanych obiektów przez ID: karta ma owner_id i collection_id. Gdy potrzebujesz samego powiązanego obiektu, nie musisz wysyłać drugiego żądania. Poproś o niego za pomocą expand[], a przyjdzie w tej samej odpowiedzi, wewnątrz 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"}
  }
}

Przykład jest skrócony: rozwinięty obiekt ma wszystkie pola własnej operacji odczytu. Pola ID zostają na swoim miejscu, więc kod, który nie używa expand[], widzi taką samą odpowiedź jak wcześniej.

Te operacje rozwijają powiązane obiekty. Ścieżka z kropką rozwija powiązanie rozwiniętego obiektu, np. collection.default_owner to domyślny właściciel kolekcji karty.

Operacja	Ścieżki
`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`

Każde powiązanie przychodzi w takiej postaci, w jakiej zwraca je operacja odczytu powiązanego obiektu:

Powiązanie	Co przychodzi w `expanded`
`collection`	Kolekcja, jak w `GET /v1/collections`.
`owner`, `verifiers`, `default_owner`	Użytkownik, jak w `GET /v1/users`: pełny wiersz dla wywołującego, który może zarządzać użytkownikami, skrócony wiersz (`brief=true`, tylko aktywni użytkownicy) dla pozostałych wywołujących. `verifiers` to lista w kolejności `verifier_ids`.
`folders`	Foldery karty w jej kolekcji, które wywołujący może widzieć, jak w `GET /v1/folders/{folder_id}` bez `path`.
`card`	Karta, jako element listy `GET /v1/cards`.
`event`	Zdarzenie, jak w `GET /v1/webhook-events/{event_id}`.

Na listach

W przypadku listy zacznij ścieżkę od data.: wtedy dotyczy ona każdego elementu strony. Tak samo jest w przypadku listy, która zwraca tablicę, np. GET /v1/cards, i listy, która trzyma swoje elementy w polu, np. jobs w GET /v1/jobs lub items w dzienniku dostarczeń.

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 wczytuje każde powiązanie dla całej strony naraz, więc rozwinięcie listy kosztuje mniej więcej tyle co jedno dodatkowe żądanie, a nie jedno żądanie na każdy element. Kursor następnej strony nie zależy od expand[], więc na następnej stronie możesz poprosić o inne powiązania.

Zasady

Do 10 ścieżek na żądanie, każda najwyżej 2 segmenty w głąb: data.owner na liście, collection.default_owner w obiekcie.
Nieznana ścieżka, więcej niż 10 ścieżek lub ścieżka głębsza niż 2 segmenty zwraca 400 z kodem api.expand_invalid. details.path wskazuje ścieżkę, a details.reason mówi, co jest nie tak: unknown_path, too_deep lub too_many_paths.
Powiązany obiekt jest rozwijany tylko dla wywołującego, który mógłby go odczytać własnym żądaniem. Klucz potrzebuje zakresu tej operacji: cards:read dla kart, kolekcji i folderów, users:read dla użytkowników, webhooks:manage dla zdarzeń. Obiekt musi też być widoczny dla wywołującego, np. należeć do kolekcji klucza, który jest ograniczony do niektórych kolekcji. W przeciwnym razie powiązanie jest rozwijane jako null, a w verifiers na miejscu użytkownika stoi null. Jego ID jest nadal zwracane. folders wymienia tylko foldery, które wywołujący może widzieć.
Klucz własnego źródła nie odczytuje kart, więc z nim card dokumentu ma zawsze wartość null. Aby pobrać kartę, wywołaj operacje push kluczem API, który ma zakresy import:write i cards:read.
Zdarzenie starsze niż 30 dni i zdarzenie dostarczenia testowego są rozwijane jako null.
expand[] tylko dodaje dane do odpowiedzi. Nigdy nie zmienia tego, co robi żądanie.