ホーム/ガイド/レスポンス展開

レスポンス展開

関連リソースをレスポンスに含める方法。

概要

多くのリソースは他のリソースへの参照（ID）を含みます。expand クエリパラメータを使用すると、参照先のオブジェクトをレスポンスに展開（インライン化）できます。これにより追加の API コールを減らすことができます。

使い方

expand クエリパラメータにカンマ区切りで展開したいフィールド名を指定します。

# Expand company and contacts on a deal
curl https://api.blueai.jp/api/v1/crm/deals/deal_11111111111111111111111111111111?expand=company,contacts \
  -b cookies.txt

デフォルトの動作

expand を指定しない場合、関連リソースは ID 文字列のみが返されます。expand を指定すると、該当フィールドが完全なオブジェクトに置き換わります。

Without expand

{
  "id": "deal_11111111111111111111111111111111",
  "name": "Big Deal",
  "company_id": "comp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

With ?expand=company

{
  "id": "deal_11111111111111111111111111111111",
  "name": "Big Deal",
  "company": {
    "id": "comp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "name": "Acme Corp",
    "domain": "acme.com"
  }
}

対応エンドポイント

expand パラメータは以下のエンドポイントで利用できます：

GET /api/v1/crm/deals — CRM 案件 — company, contacts を展開可能
GET /api/v1/crm/contacts — CRM 連絡先 — company を展開可能

使用例

const res = await fetch(
  "https://api.blueai.jp/api/v1/crm/deals?expand=company,contacts",
  { credentials: "include" },
);
const { data } = await res.json();

// company is now a full object instead of just an ID
console.log(data[0].company.name); // "Acme Corp"