In December of 2016, with the release of WordPress 4.7, a long-debated milestone came to pass: the WordPress REST API was officially included as part of WordPress Core.
Although the REST API had existed as a plugin before the official merge into core, its subsequent inclusion sparked quite a bit of debate, with arguments being made both for its inclusion and for the need for further testing.
Ultimately, the REST API was merged into Core and now powers the Block Editor as well as many 3rd-party integrations and interfaces with WordPress sites across the web.
However, for many WordPress users, this was the first time they had ever heard of the REST API of any kind, let alone one integrated so tightly into WordPress.
So in this article, we’ll take a look at just what a REST API is, how the WordPress REST API is unique, and some examples of how it works and some of the kinds of technology that are enabled now that it’s included in WordPress Core.
What is a REST API?
The term REST API is actually two acronyms in one and both are important when understanding just how the WordPress REST API works and what it does.
What is REST?
The first part, REST, stands for REpresentational State Transfer. Put as simply as possible, this is a specification that defines how two separate resources on the web should communicate with each other. These two interfaces might be two different websites, a web server, a mobile application, and much more.
A service that follows this specification is often referred to as a RESTful service, and works to ensure that the client requesting information doesn’t have to know anything about the server’s state and how the client and server can be more modular and separate than with other methods of transporting data across the Internet.
Essentially, if a developer knows they are interacting with a RESTful service, they can make certain assumptions about how their requests will be formatted and what sort of data they’ll receive in return, which is very helpful when developing interconnected technologies.
If you want to to go deeper into exactly what makes up a RESTful service and how these types of requests are made, I would highly recommend checking out Codecademy’s writeup called What is REST?
What is an API?
API stands for Application Programming Interface and, as the name implies, provides an interface for other clients and services across the web to interact with a particular application. It specifies endpoints, usually URLs, where data can be sent, whether these URLs return any data or create resources on the server and whether any particular type of authentication is required to access these endpoints.
For many popular services on the web today, APIs provide an automated way to do what a user could do manually, by allowing a script or piece of code to take the same action with a user present. For example, if you use Reddit and find yourself writing the same sort of comment on many of the threads you browse, you could create a script that searched Reddit for those types of comments and automatically posted your standard reply via Reddit’s API.
By exposing their infrastructure through an API, users don’t have to rely on brittle web scraping methods of automating these sorts of tasks and Reddit can keep track of who is accessing their resources via their API, how often they are doing so, and control for usage that is outside their terms of service.
Why did WordPress need a REST API?
If you have ever made API-like requests to WordPress prior to the REST API being part of Core, you might be familiar with the concept of admin-ajax. This was the original way of making requests like this in WordPress, where every request was routed through the admin-ajax.php file, checked for any specific actions that developers of any active plugins or themes had registered, and then used those registered functions to fulfill the requests.
As you might expect, that meant that every developer who used API-like requests enabled this functionality as part of their plugin or theme did so slightly differently and anyone who wanted to interact with this functionality had to familiarize themselves with how each plugin or theme was built. The WordPress REST API was introduced in order to standardize the way these requests were made and provide a far more wide-reaching set of endpoints that could be used to interact with WordPress Core itself.
An example request to the WordPress REST API
The WordPress REST API Handbook maintains a full list of the endpoints that are supported in the WordPress REST API out of the box. And while it’s great to have a full list, it can be a bit overwhelming. Let’s take a look at what might be considered the most basic functionality of any API interaction: fetching the API’s basic resource. In the case of WordPress, that resource is posted.
All of the WordPress REST API’s endpoints are prefixed with the URL path wp-json between the root domain and what the REST API Handbook refers to as the Base Route. This means that if we’re accessing the endpoint to list the site’s posts and the URL for our site was example.com, we would need to make a request to the URL .
Making a GET request, either by simply loading that URL up in your favorite web browser or using an API browser such as Postman, should return you a list of posts from the API, although they might not be in a format that you’re used to. If all you’re seeing is one long string of text, you are looking at a data format known as JSON. If you’re accessing the API endpoint through your browser and would like to look at this information in a more readable format, I would recommend installing the JSON Viewer extension. This will detect any output in your browser that is JSON and format it so you can more easily read it. With this installed, you should see post data output from the WordPress REST API and you’ve successfully made your first REST API request!
What else can the WordPress REST API do?
Outside of fetching a list of the latest posts on a WordPress site, looking at the Endpoint Reference, you’ll see that there are a ton of other ways you can interact with the WordPress REST API. If you are authenticated as a WordPress user, you can publish posts via the API, get a list of Themes available to the site, view and edit settings as well as much of the other functionality that’s available to be manually interacted with through wp-admin.
Some examples of the WordPress REST API in action
Exposing the ability to interact with WordPress through the REST API opened up a wide range of possibilities of sites that could now use WordPress as the backend for content management.
TechCrunch: Shortly after the WordPress REST API was announced, TechCrunch announced that it had rebuilt its site using a headless architecture, which meant that they were using WordPress on the backend as a content management system, while still being able to use a “single page style React app” on the frontend.
Block Editor (Gutenberg): Perhaps the usage of the REST API that most people have benefitted from is the WordPress Block Editor. Now the mainstream editor in WordPress, much of the Block Editor functionality is enabled by the fact that it can interact with the WordPress REST API endpoints without
All sorts of community projects: Back when the REST API was first getting considered for merge into a core, a public call went out asking people to talk more about how they were using the REST API. The answers were very wide-ranging, which you can expect from a community as large as WordPress, but included everything from plugins with more interactive interfaces than was previously possible to people building mobile apps for their clients that could consume WordPress content.
Wrapping Up
Even if you don’t have any experience with using APIs, you’ve probably used something at some point in your career that relies on the WordPress REST API to function. As interfaces continue to become more dynamic and websites start to have more actions that don’t require a page load.
Now that you know what the WordPress REST API is, you might be thinking about some things you can build with it! The REST API can definitely be a powerful tool in your toolbox to build even better WordPress themes and plugins.
If you need a bit more clarification or some examples of what’s possible, take a look at the docs and jump right in!
