リンクと埋め込み（Linking and Embedding）

リンク

レスポンスオブジェクトの _links プロパティには、「関係」によってグループ化された他のAPIリソースへのリンクのマップが含まれています。関係は、リンクされたリソースがプライマリリソースにどのように関連しているかを指定します。

例には次のものが含まれます:

– author – リソースとその著者との関係を説明

– wp:term – 投稿とそのタグまたはカテゴリとの関係を説明

関係は次のいずれかです:

– 標準化された関係

– URI relation – https://api.w.org/term のような

– または Compact URI relation – wp:term のような

コンパクトURI関係は、必要に応じて完全なURI関係に正規化して完全な互換性を確保できます。これは、HTML <link> タグや <a rel=""> リンクに似ています。

リンクは、リソースへの絶対URLを持つ href プロパティを含むオブジェクトであり、他のオプションのプロパティも含まれます。これには、コンテンツタイプ、曖昧さ解消情報、およびリンクで実行できるアクションに関するデータが含まれます。

コレクションレスポンス（オブジェクトのリストを返すもの）では、各アイテムにリンクが含まれ、トップレベルのレスポンスは Link ヘッダーを介してリンクを含みます。

クライアントライブラリがヘッダーにアクセスできない場合は、_envelope パラメータを使用して、ヘッダーをボディデータとして含めることができます。

例のレスポンス

典型的な単一投稿リクエスト (/wp/v2/posts/42):

{
  "id": 42,
  "_links": {
   "collection": [
   {
   "href": "https://example.com/wp-json/wp/v2/posts"
   }
   ],
   "author": [
   {
   "href": "https://example.com/wp-json/wp/v2/users/1",
   "embeddable": true
   }
   ]
  }
}

埋め込み

オプションとして、一部のリンクされたリソースは、必要なHTTPリクエストの数を減らすためにレスポンスに含めることができます。これらのリソースは、メインレスポンスに「埋め込まれています」。

埋め込みは、リクエストの _embed クエリパラメータ を設定することでトリガーされます。これにより、_embedded キーの下に埋め込まれたリソースが _links キーの隣に含まれます。このオブジェクトのレイアウトは _links オブジェクトに似ていますが、リンクプロパティの代わりに埋め込まれたリソースが含まれています。

embeddable フラグが true に設定されているリンクのみが埋め込むことができ、_embed はすべての埋め込み可能なリンクを埋め込む原因となります。ただし、埋め込まれたレスポンスを含む関係のみが _embedded に含まれますが、埋め込み可能なリンクと埋め込み不可能なリンクが混在する関係は、埋め込み不可能なリンクのダミーレスポンスを含み、数値インデックスが _links のものと一致するようにします。

コレクションレスポンスを埋め込む場合、たとえば /wp/v2/posts?author=1 の場合、埋め込まれたコレクションにはデフォルトのページネーション制限が適用されます。

例のレスポンス

{
  "id": 42,
  "_links": {
   "collection": [
   {
   "href": "https://example.com/wp-json/wp/v2/posts"
   }
   ],
   "author": [
   {
   "href": "https://example.com/wp-json/wp/v2/users/1",
   "embeddable": true
   }
   ]
  },
  "_embedded": {
   "author": {
   "id": 1,
   "name": "admin",
   "description": "Site administrator"
   }
  }
}