リンクと埋め込み
TOPICS
WP REST APIは、API全体にハイパーリンクを組み込んで、見つけられるようにして、関連するリソースを１つのレスポンスにまとめて埋め込みます。
REST APIは、HAL標準(Hypertext Application Language)に完全には準拠していませんが、._linksおよび._embeddedプロパティを実装しています。
リンク
レスポンスの_linksプロパティは、”relation”でグループ化された他のAPIリソースへのリンクのマップを含んでいます。
その関係は、第一のリソースにどのように関連しているかを示しています。
（例えば、”作者”を含んでいる場合は、リソースと作者の関係を説明しており、”wp:term”を含んでいる場合は、投稿とタグまたはカテゴリーの関係を説明しています。）
その関係は、URIの関係である標準化された関係（https://api.w.org/termのような）か、コンパクトURIの関係（wp:termのような）のどちらかになります。
（コンパクトURIの関係は、フルURIへの互換性があるか確かめる必要がある場合には、正規化されます）
これは、HTMLでいう<link>タグや<a ref="">リンクに似ています。
リンクは、リソースへの絶対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 クエリパラメータを設定することでトリガされます。これにより、_linksキーに隣接する_embeddedキーの下に埋め込まれたリソースが含まれます。このオブジェクトのレイアウトは _links オブジェクトを反映していますが、リンクのプロパティの代わりに埋め込みリソースが含まれます。
embeddedフラグが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"
}
}
}