Understanding the WordPress REST API’s embed feature

Getting Started

Have you ever fetched a WordPress REST endpoint and realized some of the values you need are references to other data objects? For example, the author value for a post is an ID pointing to a user. You could do another API call to grab the author value or add a custom rest field with the values you need, but that can be slow, cumbersome, and make your data logic fragile.

Fortunately, the WordPress API allows some data to be embedded into other endpoints. They’re turned off by default to help make sure responses are small and fast, but you can fetch the embedded values with a query parameter: _embed

Comparing requests with and without embedding

Here is a condensed JSON response for a post on this website. The REST endpoint URL is [<https://indexforwp.com/wp-json/wp/v2/posts/1249>](<https://indexforwp.com/wp-json/wp/v2/posts/1249>) and the response looks like this (some fields have been removed for easier scanning):

{
    "id": 1249,
    "status": "publish",
    "title": {
        "rendered": "Generating WordPress Application Passwords for your third party apps"
    },
    "author": 1,
    "featured_media": 1251,
    "_links": {
        "author": [
            {
                "embeddable": true,
                "href": "<http://theory.local/wp-json/wp/v2/users/1>"
            }
        ],
        "wp:featuredmedia": [
            {
                "embeddable": true,
                "href": "<http://theory.local/wp-json/wp/v2/media/1251>"
            }
        ],
    }
}

As you can see, the author and featured media values are IDs that point to a user and attachment. This isn’t very useful when trying to display values on the frontend, but if you look at the _links field, you can see REST urls for the author and featured media, along with an "embeddable": true value.

When a linked resource has the embeddable value, it means that the value will be pulled if you request if via the _embedquery parameter. Here’s the same response with that query: https://indexforwp.com/wp-json/wp/v2/posts/1249?_embed

{
    "id": 1249,
    "status": "publish",
    "title": {
        "rendered": "Generating WordPress Application Passwords for your third party apps"
    },
    "author": 1,
    "featured_media": 1251,
    "_links": {
        "author": [
            {
                "embeddable": true,
                "href": "<http://theory.local/wp-json/wp/v2/users/1>"
            }
        ],
        "wp:featuredmedia": [
            {
                "embeddable": true,
                "href": "<http://theory.local/wp-json/wp/v2/media/1251>"
            }
        ],
    },
    "_embedded": {
        "author": [
            {
                "id": 1,
                "name": "David Woolf",
                "url": "<http://theory.local>",
                "description": "",
                "link": "<http://theory.local/author/david/>",
                "slug": "david",
                "avatar_urls": {
                    "24": "<http://0.gravatar.com/avatar/c2b06ae950033b392998ada50767b50e?s=24&d=mm&r=g>",
                    "48": "<http://0.gravatar.com/avatar/c2b06ae950033b392998ada50767b50e?s=48&d=mm&r=g>",
                    "96": "<http://0.gravatar.com/avatar/c2b06ae950033b392998ada50767b50e?s=96&d=mm&r=g>"
                }
            }
        ],
        "wp:featuredmedia": [
            {
                "id": 1251,
                "date": "2021-09-18T14:19:35",
                "slug": "application",
                "type": "attachment",
                "link": "<http://theory.local/application/>",
                "title": {
                    "rendered": "application"
                },
                "author": 1
            }
        ]
    }
}

Now we have an _embedded object with our author and featured media values (there are many more fields in each embed that have been removed for readability).

Wrap Up

Embedding is a handy way to request a fuller picture of a resource when displaying it to the end user, but be aware that it makes your requests bigger. If you don’t need those values, make sure to remove the _embed parameter, otherwise use it to reduce HTTP requests to your visitors.