WordPress didn’t become the world’s most popular content management system by being exclusive. The tool is free, open-source, beginner-friendly, highly flexible, and always evolving.
According to many experts, the next step in the evolution of WordPress is its REST API, and we think that makes it worth checking out.
The WordPress REST API vastly expands WordPress’s capabilities — it opens the CMS up to more easily connect with other programs. Now, besides being a way to build and manage websites, developers can leverage WordPress like a service, taking only the functionality they need. It’s a new way to build with WordPress.
APIs are a more complex topic in the realm of marketing. So, in this guide, we’ll explain what APIs are and what REST is. Then, we’ll explore how developers use the WordPress REST API to bypass its limitations. Let’s get started.
What is the WordPress REST API?
The WordPress REST API is an API that allows external applications to access data and functionality of the WordPress CMS. This API lets developers integrate WordPress into third-party web applications and websites without needing to log into WordPress.
If you’re new to the terms API and REST, that definition might not make complete sense just yet. Let’s briefly cover what APIs and REST APIs are and why they matter here.
What is an API?
An application programming interface, or API, is a part of a piece of software that allows two applications to communicate with each other. An API exposes a portion of an application’s data and functionality, enabling integration by third-party applications.
For example, say you wanted to display a YouTube video on your website. Since the video is owned by YouTube and stored on a YouTube server, you have to request the video through YouTube’s API. After the API receives and approves your request, it sends the video back to you, and you can embed the video as desired.
Or, say you want your application to upload a video to YouTube — YouTube’s API lets you do this as well. This time, you make a different request asking to upload your content. If the API approves, the video uploads without requiring you to log into a YouTube user account.
APIs make today’s software ecosystem possible. Through APIs, disparate software applications can integrate and share data in an automated and standardized way. Whether it’s your automation software scheduling your social media posts or the weather app on your phone, most of your favorite apps employ APIs in some way.
To learn more about who APIs work and when they’re used, see our complete guide to APIs.
What is a REST API?
When we’re talking about APIs on the web, we’re usually talking about a type of API called a REST API. REST, short for Representational State Transfer, is a set of guidelines for building web APIs. APIs that follow these guidelines are REST APIs (or RESTful APIs).
For a more detailed look at REST APIs, check out our dedicated post. For now, we can briefly summarize the five requirements of REST APIs since these govern how the WordPress REST API works. These requirements are:
- Client-server separation: The application hosting the API (called the “server”) and the application using the API (called the “client”) are kept as separate systems. They may only communicate via a request from the client followed by a response from the server.
- Uniform interface: All requests and responses must follow a common protocol. In most cases, REST APIs use the Hypertext Transfer Protocol (HTTP) to communicate over the internet.
- Stateless: All interactions with an API are independent of each other. Every request and response should contain all information necessary to complete the interaction without referencing previous requests/responses.
- Layered system: Rarely are the client and server directly connected over a network. Usually, proxy servers exist between them to handle traffic, performance, and security. RESTful requests and responses should always be formatted the same, regardless of how many layers exist between client and server.
- Cacheable: If a client requests resources (i.e., data) from the server, the server should indicate whether the provided resource may be cached by the client and for how long.
These constraints standardize how web applications talk to each other. They ensure that any interaction with any REST API follows a similar process. It also keeps the two applications independent, such that changes or upgrades to either application will not affect communication between them.
What does the WordPress REST API do?
The WordPress REST API is, as the name implies, a REST API, so it operates along the guidelines listed above.
Specifically, the WordPress REST API exposes WordPress's inner workings to outside developers, which makes it possible to integrate WordPress with other applications in numerous ways. And, since REST is so common in web APIs, this makes the WordPress REST API relatively easy for any developer to learn and use.
Originally developed as an open-source WordPress plugin, the WordPress REST API was added to WordPress core in version 4.7, released in 2016. This was a major step for WordPress, effectively turning it into a software platform. Now, developers could build with WordPress without having to build within it.
For example, you might want to build a web application from scratch but harness WordPress’s content management and article drafting features. With the WordPress REST API, you can fetch post content from your WordPress account and then publish it on your custom web application. Or, you might connect WordPress to a mobile app you’re building with the REST API. You’re probably familiar with the Gutenberg block editor — this is a real example of a web app that uses the WordPress REST API to retrieve and modify content in the WordPress database.
Lastly, note that the WordPress REST API is one of several APIs maintained by WordPress. These other WordPress APIs mainly exist to allow plugins and themes to interact with WordPress core.
How to Use the WordPress REST API
Before we experiment with posting and receiving WordPress data, let’s review some key terms to know for using the WordPress REST API.
WordPress REST API Terms
First off, a request is what you send to the WordPress REST API. It specifies what resource in the WordPress database you want to target, and what you want to do with it.
A response is what the API sends back after your request. It contains any data that you requested, as well as a confirmation if the request was successful or an error message if not.
A route is a URL used to locate a resource through the WordPress API, like a post, page, metadata, user, or other data type. For example, the route “http://yourwebsite.com/wp-json/wp/v2/pages” is used to access the pages on a WordPress website.
Routes are used in endpoints to access or modify data through the API. An endpoint combines a route with a command called an HTTP method. The four HTTP methods you’ll probably use most often are:
- GET: This method retrieves data from the server.
- POST: This method adds data to the server.
- PUT: This method edits data already on the server.
- DELETE: This method removes data from the server.
For instance, an endpoint that retrieves all WordPress pages from yourwebsite.com would look like this:
An endpoint that adds a new page to yourwebsite.com looks like this:
The WordPress Developer Reference lists all of the REST API’s routes and endpoints, which let you access and manipulate virtually anything on your WordPress site. Most if not all of your interactions with the WordPress API will utilize these endpoints.
Depending on how you use the REST API, you may also need to provide authentication to make requests. For many requests, WordPress needs to verify who you are first. By default, most public content on your website you can access with the API without authentication, while accessing private data requires authentication.
Make a Request to the WordPress REST API
With the basic terminology down, we now know enough to send simple requests to the REST API. We don’t recommend testing the REST API on your live website — instead, set up a test website on a server or locally to make requests.
The simplest way to make manual API requests is through the command-line interface (CLI), a program with which you write text-based commands to your computer’s operating system. On Windows, the default CLI program is Command Prompt. On macOS, it’s Terminal.
To communicate with an API from the command line, you can use cURL, a free tool to make HTTP requests (among many other types of requests). You might also try WP-CLI, a free command-line interface specifically for WordPress that lets you interact with your WordPress website without using your browser.
To start, use cURL or WP-CLI to access your remote or local test site via SSH. If prompted, enter your credentials for authentication.
Once you’ve accessed your test site, you can start sending requests. The base route for your API requests is
… where “yourwebsite.com” is your domain. You’ll add subdirectories to the end of this URL in order to request specific data.
Let’s start with our previous example, getting all pages from your WordPress site. The endpoint for this action is:
If instead you want to retrieve a specific page, you can do that by adding the page id to the end of the route:
… where <id> is the numeric id of the page.
Next, let’s experiment with the POST method. We can use POST to add a new page to a website with the following syntax:
This adds a blank page to your website which you can populate with content.
What if you want to get information about a specific user in your WordPress account? This is also possible with a simple request:
… where <id> is the numeric id of the user.
We’re only scratching the surface of what’s possible here – to make the most of the WordPress REST API, your requests will be much more complex. However, if you’re just getting the hang of WordPress APIs and APIs in general, it’s worth practicing simpler requests to gain a solid grasp of the fundamentals.
WordPress REST API Examples
We’ve seen how developers can request information and make changes via WordPress’s REST API — now, let’s check out some examples of what this API looks like in action.
The WordPress Gutenberg editor application implements the WordPress REST API to access page and post information. It fetches page and post data, including text and media, from the WordPress database and allows you to place your content with blocks — a simple example of the API at work.
AppPresser lets users create iOS and Android mobile apps that integrate with WordPress websites. It calls the WordPress REST API to retrieve content from WordPress and to modify database contents as dictated by your mobile app.
Shortly after the release of the WordPress REST API as a part of WordPress core, popular technology publication Wired used the API to make a synced copy of their main site for testing. Whenever the main website updated its content, the test site changed to match.
Event Espresso is an event management and ticketing plugin for WordPress that makes use of the WordPress REST API. With an add-on, site owners can make event information available to developers, so event information can be used by external apps and websites.
When to Use the WordPress Rest API
The WordPress REST API is great for two main cases. First, if you want to integrate WordPress into an application or website you’re building (that isn’t itself made with WordPress), you can accomplish this with the REST API.
However, there are cases where this API isn’t necessary. Namely, if you want to develop a theme or plugin with PHP, try leveraging WordPress’s other APIs, like the Plugin API and Theme Customization API. Website owners can also accomplish a lot looks-wise with the right WordPress theme and some extensive customization.
In short, the WordPress REST API isn’t always the right solution, but when it is, it’s powerful. The WordPress API documentation puts it well: “If you want a structured, extensible, and simple way to get data in and out of WordPress, you probably want to use the REST API.”
Build with WordPress, outside of WordPress.
If you want to stay up-to-date with how the WordPress CMS is growing and adapting, you’ll want to understand at least the basics of its REST API. The WordPress REST API acts as a gateway to the greater application ecosystem. Now, software of all kinds can leverage WordPress technology outside of the tool.
If you’re not a developer, it still helps to know how the REST API works, just in case you decide to integrate WordPress with your tools in any way. With some extra knowledge, you can diagnose problems, collaborate with devs, and maybe one day make custom integrations yourself.
Originally published Oct 26, 2021 7:00:00 AM, updated October 26 2021