注文を返すとき、その注文をした顧客の情報をどう含めるか、2つの返し方があります。参照は、関連データをidだけで返す方法です。例えばorder.customer_idのように顧客のidだけを返し、顧客の名前などが必要なら、クライアントが別のリクエストで取得します。

埋め込みは、関連データを中身ごとレスポンスに含める方法です。例えばorder.customer: { id, name }のように顧客の情報をそのまま返します。クライアントがほぼ毎回、注文と顧客の両方を必要とするなら、追加のリクエストが要らなくなります。

?include=customerを付けると、クライアントがリクエストごとに「顧客も埋め込んでほしい」と指定できます。サーバーが常にどちらかに決める必要はありません。

ただし、APIの設計者は、埋め込みを何段も重ねないようにします。注文に顧客を、その顧客にまた注文を、その注文にさらに明細を埋め込んでいくと、サーバーが返すレスポンスは際限なく大きくなります。顧客の注文の中に同じ顧客が再び含まれるなど、同じデータが自分自身の中に繰り返し含まれることもあります。そのためサーバーは、埋め込みを通常1段までにとどめ、それより深いデータは、クライアントが別のリクエストで取得します。