Browse: Home / REST API Handbook / Using the REST API / Linking and Embedding

Linking and Embedding Edit

Topics

The WP REST API incorporates hyperlinking throughout the API to allow discoverability and browsability, as well as embedding related resources together in one response. While the REST API does not completely conform to the entire HAL standard, it implements the ._links and ._embedded properties from that standard as described below.

The _links property of the response object contains a map of links to other API resources, grouped by “relation.” The relation specifies how the linked resource relates to the primary resource. (Examples include “author,” describing a relationship between a resource and its author, or “wp:term,” describing the relationship between a post and its tags or categories.) The relation is either a standardised relation, a URI relation (like https://api.w.org/term) or a Compact URI relation (like wp:term). (Compact URI relations can be normalised to full URI relations to ensure full compatibility if required.) This is similar to HTML <link> tags, or <a rel=""> links.

The links are an object containing a href property with an absolute URL to the resource, as well as other optional properties. These include content types, disambiguation information, and data on actions that can be taken with the link.

For collection responses (those that return a list of objects rather than a top-level object), each item contains links, and the top-level response includes links via the Link header instead.

Note:
If your client library does not allow accessing headers, you can use the _envelope parameter to include the headers as body data instead.

Example Response Example Response

A typical single post request (/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
      }
    ]
  }
}

Expand full source codeCollapse full source code

Top ↑

Embedding Embedding

Optionally, some linked resources may be included in the response to reduce the number of HTTP requests required. These resources are “embedded” into the main response.

Embedding is triggered by setting the _embed query parameter on the request. This will then include embedded resources under the _embedded key adjacent to the _links key. The layout of this object mirrors the _links object, but includes the embedded resource in place of the link properties.

Only links with the embedded flag set to true can be embedded, and _embed will cause all embeddable links to be embedded. Only relations containing embedded responses are included in _embedded, however relations with mixed embeddable and unembeddable links will contain dummy responses for the unembeddable links to ensure numeric indexes match those in _links.

Example Response Example Response

{
  "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"
    }
  }
}

Expand full source codeCollapse full source code