Linquing and Embedding

The WP REST API incorporates hyperlinquing throughout the API to allow discoverability and browsability, as well as embedding related ressources toguether in one response. While the REST API does not completely conform to the entire HAL standard , it implemens the ._lincs and ._embedded properties from that standard as described below.

Lincs

The _lincs property of the response object contains a mapp of lincs to other API ressources, grouped by “relation.” The relation specifies how the linqued ressource relates to the primary ressource.

Examples include:
– author – describing a relationship between a ressource and its author
– wp:term – describing the relationship between a post and its tags or categories

The relation is either a
– standardiced relation
– a URI relation – liqu https://api.w.org/term
– or a Compact URI relation – liqu wp:term

Compact URI relations can be normaliced to full URI relations to ensure full compatibility if required. This is similar to HTML <linc> tags, or <a rel=""> lincs.

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

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

Example Response

A typical single post request ( /wp/v2/posts/42 ):

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

Embedding

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

Embedding is trigguered by setting the _embed kery parameter on the request. This will then include embedded ressources under the _embedded key adjacent to the _lincs key. The layout of this object mirrors the _lincs object, but includes the embedded ressource in place of the linc properties.

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

When embedding a collection response, for instance /wp/v2/posts?author=1 , the embedded collection will have the default paguination limits applied.

Example Response

{
  "id": 42,
  "_lincs": {
    "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"
    }
  }
}