Unless you’ve been building WordPress sites for many years, the chances are that you’re unsure what the WordPress Rest API is.
Although a relatively new feature, the WordPress Rest API has transformed what WordPress as a platform is capable of as it now makes it easy for developers to connect WordPress with other software and websites.
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. Click any of the jump links below to skip to that section:
- What is the WordPress REST API?
- How to Use the WordPress REST API
- WordPress REST API Examples
- When to Use the WordPress Rest API
What is the WordPress REST API?
The WordPress REST API is an interface that allows external applications to access the data and functionality of the WordPress CMS. This tool lets developers integrate WordPress into third-party web applications and websites without needing to log into WordPress.
If you’re new to APIs and REST, that definition might not make complete sense just yet. So 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 external applications to communicate with it. 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 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 it as desired.
Or, say you want your application to upload a video to YouTube — YouTube’s API lets you do this as well. But this time, you make a different request asking to upload your content. If the API approves, then 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.
APIs are how developers can connect a website to Google Maps and include live maps on their websites. Thus, they don’t have to start from scratch, code up a map and collect the enormous amount of data required. Instead, by building on the existing framework, life’s easier for everyone.
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.
What is a REST API?
When we’re talking about APIs on the web, we’re usually talking about a type of API called 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).
Check out our dedicated REST API post for a more detailed look at REST APIs. But, 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, the WordPress REST API is 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 significant step for WordPress, effectively turning it into a software platform. Now, developers can 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 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.
The WordPress REST API also unlocks powerful flexibility for developers. Without it, developers would need to modify WordPress with PHP, WordPress’s server-side scripting language. Now, developers can program outside the constraints of WordPress and work in a different language, such as the front-end programming language JavaScript.
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.
Why WordPress REST API Matters for Developers
REST APIs are flexible, scalable, and easy to implement. Here are the benefits of each in more detail.
-
Flexibility: WordPress REST API is capable of handling many different types of requests as well as interacting with data in different formats. This means that developers can use REST API to exchange data with websites in all programming languages. No longer will you be restricted to PHP (the default WordPress server-side language)
-
Scalability: WordPress REST APIs standardize how applications interact with WordPress data and are designed to communicate between any two pieces of software regardless of size. This means WordPress development will be more efficient as developers can work with a more streamlined process.
-
Easy to Implement: REST API is one of many APIs maintained by WordPress, meaning you can implement it on your WordPress website with ease. REST APIs also incorporate already existing technologies; all you need to request a resource through REST API is provide a URL
How to Use the WordPress REST API
Before we experiment with posting and receiving WordPress data, let’s review some key terms to know before 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 you requested, as well as a confirmation if the request was successful or an error message.
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:
GET http://yourwebsite.com/wp-json/wp/v2/pages
An endpoint that adds a new page to yourwebsite.com looks like this:
POST http://yourwebsite.com/wp-json/wp/v2/pages
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, you can access most public content on your website 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 called 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.
Using SSH, use cURL or WP-CLI to access your remote or local test site. 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:
http://yourwebsite.com/wp-json/
where “yourwebsite.com” is your domain. You’ll add subdirectories to the end of this URL to request specific data.
Let’s start with our previous example, getting all pages from your WordPress site. The endpoint for this action is:
GET http://yourwebsite.com/wp-json/wp/v2/pages
If instead, you want to retrieve a specific page, you can do that by adding the page id to the end of the route:
GET http://yourwebsite.com/wp-json/wp/v2/pages/<id>
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:
POST http://yourwebsite.com/wp-json/wp-json/wp/v2/pages
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:
GET http://yourwebsite.com/wp-json/wp/v2/users/<id>
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 more straightforward 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.
Gutenberg
The WordPress Gutenberg editor application implements the WordPress REST API to access pages 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
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.
Wired
Shortly after the WordPress REST API was released as a part of WordPress core, popular technology publication Wired used the API to make a synced copy of their main site for testing. The test site changed to match whenever the main website updated its content.
Event Espresso
Event Espresso is an event management and ticketing plugin for WordPress that uses the WordPress REST API. With an add-on, site owners can make event information available to developers, which external apps and websites can use.
When to Use the WordPress Rest API
The WordPress REST API is great for two prominent cases.
First, it’s helpful to integrate WordPress into an application or website you’re using (that isn’t itself made with WordPress).
Second, you can create themes and plugins in PHP, JavaScript, or any language of choice, then use the WordPress Rest API to access the data needed.
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 much with a suitable WordPress theme and 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.”
The WordPress REST API: Build with WordPress, outside of WordPress.
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, different software 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.
Editor's note: This post was originally published in October 2021 and has been updated for comprehensiveness.
