Ссылки и встраивания

WP REST API добавляет ссылки на возможные маршруты во всех ответах API, это позволяет узнать какие еще связанные маршруты возможны. REST API не полностью соответствует HAL стандарту, но свойства ._links и ._embedded тут используются так как описано ниже.

Оглавление:

_links (ссылки)

Это свойство в json данных ответа содержит карту ссылок на другие связанные с текущим запросом ресурсы. Связь показывает как указанные в _links ресурсы относятся к основному ресурсу. Например:

  • author — показывает автора текущего ресурса (например поста) и показывает маршрут этого автора.
  • wp:term — показывает какие у поста есть метки или рубрики и по каким маршрутам к ним можно обратиться.

Связи похожи на HTML теги <link> или ссылки вида <a rel="">.

Связь может быть указана как:

  • Стандартная.
  • URI — например https://api.w.org/term.
  • Компактный URI — например wp:term. Компактный URI, для обеспечения полной совместимости, может быть преобразован в полный вид.

Каждая связь в _links содержит объект данных, в котором указаны:

  • href — это ссылка (маршрут).
  • другие свойства — тип контента, дополнительная информация, данные о том что можно сделать со ссылкой.

Пример ответа /wp-json/wp/v2/posts/42

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

Пример /wp-json/wp/v2/comments/1

{
	"id": 1,
	...
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/comments/1"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/comments"
			}
		],
		"up": [
			{
				"embeddable": true,
				"post_type": "post",
				"href": "http://example.com/wp-json/wp/v2/posts/11"
			}
		]
	}
}

Пример /wp-json/wp/v2/posts/72

{
	"id": 72,
	...
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts/72"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/types/post"
			}
		],
		"author": [
			{
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/users/1"
			}
		],
		"replies": [
			{
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/comments?post=72"
			}
		],
		"version-history": [
			{
				"count": 8,
				"href": "http://example.com/wp-json/wp/v2/posts/72/revisions"
			}
		],
		"predecessor-version": [
			{
				"id": 97,
				"href": "http://example.com/wp-json/wp/v2/posts/72/revisions/97"
			}
		],
		"wp:attachment": [
			{
				"href": "http://example.com/wp-json/wp/v2/media?parent=72"
			}
		],
		"wp:term": [
			{
				"taxonomy": "category",
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/categories?post=72"
			},
			{
				"taxonomy": "post_tag",
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/tags?post=72"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	}
}

Для запросов коллекций (когда возвращается список объектов), свойство _links, присутствует в каждом элементе списка. А ссылка на верхний уровень ресурса находится в заголовке ответа в свойстве Link.

Если ваш клиент не умеет читать заголовки ответа, то их можно поместить в сам ответ указав параметр _envelope.

Пример /wp-json/wp/v2/posts/72

Золовки ответа:

Access-Control-Allow-Headers : Authorization, Content-Type
Access-Control-Expose-Headers: X-WP-Total, X-WP-TotalPages
Allow                        : GET, POST, PUT, PATCH, DELETE
Cache-Control                : no-cache, must-revalidate, max-age=0
Connection                   : Keep-Alive
Content-Length               : 5459
Content-Type                 : application/json; charset=UTF-8
Date                         : Wed, 29 Aug 2018 23:48:25 GMT
Expires                      : Wed, 11 Jan 1984 05:00:00 GMT
Keep-Alive                   : timeout=10, max=99
Link                         : <http://example.com/provrka-klika-po-ssylke/>; rel="alternate"; type=text/html
Server                       : Apache
X-Content-Type-Options       : nosniff
X-Robots-Tag                 : noindex

_embed (встраивания)

Некоторые ответы содержат ссылки на связанные ресурсы (маршурты), такие ссылки располагаются под ключем _links. Например, пост может содержать ссылку на родительский пост или ссылку на комментарии к посту.

Связанные ресурсы у которых есть возможность встраивания (свойство embeddable = true) можно сразу добавить в ответ, чтобы получить все данные в одном запросе и не создавать дополнительных HTTP запросов. Так, клиенты могут получить сам ресурс, а также связанные с ним данные в одном запросе.

Для этого при запросе нужно указать параметр запроса ?_embed. В этом случае, связанные ресурсы будут встроены в тело ответа и будут расположены под ключом _embedded

Пример

Отправим обычный запрос:

GET http://example.com/wp-json/wp/v2/posts/113
{
	"id": 113,
	"date": "2018-08-17T02:57:44",
	...
	"categories": [ 1 ],
	"tags": [],
	"_links": {
		"self": [
			{ "href": "http://example.com/wp-json/wp/v2/posts/113" }
		],
		...
	}
}

Теперь отправим _embed запрос:

GET http://example.com/wp-json/wp/v2/posts/113?_embed
{
	"id": 113,
	"date": "2018-08-17T02:57:44",
	...
	"categories": [ 1 ],
	"tags": [],
	"_links": {
		"self": [
			{ "href": "http://example.com/wp-json/wp/v2/posts/113" }
		],
		...
	},
	"_embedded": {
		"author": [
			{
				"id": 1,
				"name": "kama",
				"url": "",
				"description": "",
				"link": "http://example.com/author/kama/",
				"slug": "kama",
				"avatar_urls": {
					"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g",
					"48": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=48&d=mm&r=g",
					"96": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=96&d=mm&r=g"
				},
				"_links": {
					"self": [
						{
							"href": "http://example.com/wp-json/wp/v2/users/1"
						}
					],
					"collection": [
						{
							"href": "http://example.com/wp-json/wp/v2/users"
						}
					]
				}
			}
		],
		"wp:term": [
			[
				{
					"id": 1,
					"link": "http://example.com/cat/my-plugins/",
					"name": "My Plugins",
					"slug": "my-plugins",
					"taxonomy": "category",
					"_links": {
						"self": [
							{
								"href": "http://example.com/wp-json/wp/v2/categories/1"
							}
						],
						"collection": [
							{
								"href": "http://example.com/wp-json/wp/v2/categories"
							}
						],
						"about": [
							{
								"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
							}
						],
						"wp:post_type": [
							{
								"href": "http://example.com/wp-json/wp/v2/posts?categories=1"
							}
						],
						"curies": [
							{
								"name": "wp",
								"href": "https://api.w.org/{rel}",
								"templated": true
							}
						]
					}
				}
			],
			[]
		]
	}
}

Пример ответа /wp-json/wp/v2/posts/42?_embed

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

Пример /wp-json/wp/v2/posts/72?_embed

{
	"id": 72,
	...
	"_links": {
		"self": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts/72"
			}
		],
		"collection": [
			{
				"href": "http://example.com/wp-json/wp/v2/posts"
			}
		],
		"about": [
			{
				"href": "http://example.com/wp-json/wp/v2/types/post"
			}
		],
		"author": [
			{
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/users/1"
			}
		],
		"replies": [
			{
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/comments?post=72"
			}
		],
		"version-history": [
			{
				"count": 8,
				"href": "http://example.com/wp-json/wp/v2/posts/72/revisions"
			}
		],
		"predecessor-version": [
			{
				"id": 97,
				"href": "http://example.com/wp-json/wp/v2/posts/72/revisions/97"
			}
		],
		"wp:attachment": [
			{
				"href": "http://example.com/wp-json/wp/v2/media?parent=72"
			}
		],
		"wp:term": [
			{
				"taxonomy": "category",
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/categories?post=72"
			},
			{
				"taxonomy": "post_tag",
				"embeddable": true,
				"href": "http://example.com/wp-json/wp/v2/tags?post=72"
			}
		],
		"curies": [
			{
				"name": "wp",
				"href": "https://api.w.org/{rel}",
				"templated": true
			}
		]
	},
	"_embedded": {
		"author": [
			{
				"id": 1,
				"name": "kama",
				"url": "",
				"description": "",
				"link": "http://example.com/author/kama/",
				"slug": "kama",
				"avatar_urls": {
					"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g",
					"48": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=48&d=mm&r=g",
					"96": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=96&d=mm&r=g"
				},
				"_links": {
					"self": [
						{
							"href": "http://example.com/wp-json/wp/v2/users/1"
						}
					],
					"collection": [
						{
							"href": "http://example.com/wp-json/wp/v2/users"
						}
					]
				}
			}
		],
		"wp:term": [
			[
				{
					"id": 1,
					"link": "http://example.com/cat/my-plugins/",
					"name": "My Plugins",
					"slug": "my-plugins",
					"taxonomy": "category",
					"_links": {
						"self": [
							{
								"href": "http://example.com/wp-json/wp/v2/categories/1"
							}
						],
						"collection": [
							{
								"href": "http://example.com/wp-json/wp/v2/categories"
							}
						],
						"about": [
							{
								"href": "http://example.com/wp-json/wp/v2/taxonomies/category"
							}
						],
						"wp:post_type": [
							{
								"href": "http://example.com/wp-json/wp/v2/posts?categories=1"
							}
						],
						"curies": [
							{
								"name": "wp",
								"href": "https://api.w.org/{rel}",
								"templated": true
							}
						]
					}
				}
			],
			[]
		]
	}
}