関連オブジェクトの展開

オブジェクトは関連オブジェクトをIDで参照します。たとえばカードにはowner_idとcollection_idがあります。関連オブジェクトそのものが必要なときも、2回目のリクエストは不要です。expand[]で指定すると、同じレスポンスの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"}
  }
}

この例は省略しています。展開されたオブジェクトには、そのオブジェクト自身を読み取る操作のすべてのフィールドが含まれます。IDのフィールドはそのまま残るので、expand[]を使わないコードには以前と同じレスポンスが返ります。

関連オブジェクトを展開できるのは、次の操作です。ドットを含むパスは、展開したオブジェクトのリンクを展開します。たとえばcollection.default_ownerは、カードのコレクションのデフォルトの担当者です。

操作	パス
`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`

各リンクは、関連オブジェクトを読み取る操作と同じ形式で返されます。

リンク	`expanded`に含まれるもの
`collection`	コレクション。`GET /v1/collections`と同じ形式です。
`owner`、`verifiers`、`default_owner`	ユーザー。`GET /v1/users`と同じ形式です。ユーザーを管理できる呼び出し元には完全な項目、それ以外の呼び出し元には簡易リストの項目（`brief=true`、有効なユーザーのみ）が返ります。`verifiers`は`verifier_ids`の順に並んだリストです。
`folders`	呼び出し元が参照できる、コレクション内のカードのフォルダー。`path`なしの`GET /v1/folders/{folder_id}`と同じ形式です。
`card`	カード。`GET /v1/cards`の項目と同じ形式です。
`event`	イベント。`GET /v1/webhook-events/{event_id}`と同じ形式です。

リストでの展開

リストでは、パスをdata.で始めます。ページのすべての項目に適用されます。これは、GET /v1/cardsのように配列を返すリストでも、GET /v1/jobsのjobsや配信ログのitemsのように項目をフィールドに入れて返すリストでも同じです。

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はリンクごとにページ全体をまとめて読み込むので、リストの展開にかかるコストは、項目ごとのリクエストではなく、追加のリクエスト1回分ほどです。次のページのカーソルはexpand[]に左右されないので、次のページでは別のリンクを指定できます。

ルール

1回のリクエストで指定できるパスは10個まで、深さはそれぞれ2セグメントまでです。リストではdata.owner、オブジェクトではcollection.default_ownerのように指定します。
不明なパス、10個を超えるパス、または2セグメントより深いパスを指定すると、コードapi.expand_invalidとともに400が返ります。details.pathはそのパスを示し、details.reasonは問題の内容を示します（unknown_path、too_deep、too_many_paths）。
関連オブジェクトが展開されるのは、呼び出し元がそのオブジェクトを個別のリクエストで読み取れる場合だけです。キーにはその操作のスコープが必要です。カード、コレクション、フォルダーにはcards:read、ユーザーにはusers:read、イベントにはwebhooks:manageです。さらに、オブジェクトが呼び出し元から参照できる必要があります。たとえば一部のコレクションに限定されたキーでは、そのコレクションの中にあることが必要です。そうでない場合、リンクはnullとして展開され、verifiersではそのユーザーの位置がnullになります。そのIDは引き続き返されます。foldersには、呼び出し元が参照できるフォルダーだけが含まれます。
ソースキーではカードを読み取れないため、ソースキーを使うとドキュメントのcardは常にnullになります。カードを取得するには、import:writeとcards:readのスコープを持つAPIキーでプッシュAPIを呼び出してください。
30日より古いイベントと、テスト配信のイベントはnullとして展開されます。
expand[]はレスポンスにデータを追加するだけです。リクエストの処理内容は変わりません。