Links and Embeddings

The WP REST API adds links to possible routes in all API responses, allowing you to know what other related routes are available. The REST API does not fully comply with the HAL standard, but the properties ._links and ._embedded are used here as described below.

Contents:

_links (links)

This property in the JSON response data contains a map of links to other resources related to the current request resources. The relationship shows how the resources specified in _links relate to the main resource. For example:

  • author — shows the author of the current resource (for example, a post) and shows the route to that author.
  • wp:term — shows what tags or categories a post has and what routes can be used to access them.

Links are similar to HTML tags <link> or links of the type <a rel="">.

A link can be specified as:

  • Standard.
  • URI — for example, https://api.w.org/term.
  • Compact URI — for example, wp:term. A compact URI can be converted to its full form to ensure complete compatibility.

Each link in _links contains a data object that specifies:

  • href — this is the link (route).
  • other properties — content type, additional information, data about what can be done with the link.

Example response /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
			}
		]
	}
}

Example /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"
			}
		]
	}
}

Example /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
			}
		]
	}
}

For collection requests (when a list of objects is returned), the _links property is present in each item of the list. A link to the top-level resource is found in the response header in the Link property.

If your client cannot read response headers, they can be included in the response itself by specifying the _envelope parameter.

Example /wp-json/wp/v2/posts/72

Response headers:

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 (embeddings)

Some responses contain links to related resources (routes), these links are located under the _links key. For example, a post may contain a link to a parent post or a link to comments on the post.

Related resources that have the possibility of embedding (property embeddable = true) can be included directly in the response to get all the data in a single request without making additional HTTP requests. Thus, clients can obtain the resource itself as well as the related data in one request.

To do this, the request must specify the query parameter ?_embed. In this case, related resources will be embedded in the response body and will be located under the _embedded key.

Example

Let’s send a regular request:

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" }
		],
		...
	}
}

Now let’s send an _embed request:

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
							}
						]
					}
				}
			],
			[]
		]
	}
}

Example response /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"
	}
  }
}

Example /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
							}
						]
					}
				}
			],
			[]
		]
	}
}