If you’re planning to become a WordPress developer, you’ll come across something called ‘REST API.’ This is an interface that expands the functionality of WordPress and enables you to connect the platform with other applications. Some developers find it really helpful as part of their process — especially if they’re looking to implement advanced functionality.
Fortunately, you don’t need to be an experienced developer to gain expertise with the WordPress REST API. Once you have a solid understanding of the interface and how it works, you can easily implement it into your web-building projects.
In this post, we’ll provide an in-depth guide to the WordPress REST API. We’ll discuss what it is, how to use it, and how to protect it against threats. We’ll also show you how to fix common REST API errors, how to use the interface with other frameworks, and how it compares to other WordPress API solutions. Finally, we’ll cover some frequently asked questions.
What is the WordPress REST API?
To understand the WordPress REST API, we’ll need to break down its various components. Let’s start with an introduction to APIs.
What is an API?
An application programming interface (API) is a program that enables two applications to communicate with one another. It serves as an intermediary between two pieces of software, facilitating a seamless collaboration.
For example, if you wanted to display a Google product on your site, like maps, you’d need to use the Google Maps API.
This enables your WordPress site to communicate with Google Maps, so it can pull all the relevant data and features needed to display those maps.
Like Google, other companies have APIs and provide them to web developers. These products can be very appealing, as they eliminate the need to code a feature (like a map) from scratch. Instead, you can use third-party software and connect it to your site via API.
What is REST?
Representational State Transfer (REST) is a set of guidelines that developers must follow when creating APIs. Therefore, a REST API is an interface that was built with these standards in mind.
Typically, a REST API follows these principles:
- Client-server separation: The API should enable the client (or website) and the server to remain separate from one another and continue functioning independently of each other.
- Caching: REST APIs should use cacheable data, when possible, to improve performance and let the website know which information can be cached.
- Statelessness: REST APIs can’t store any information about the website they’re connected to on their server, and only the information needed to process a request should be provided.
- A uniform interface: Requests for resources should be processed in the same way, regardless of their origin.
- Layered architecture: REST APIs are built around a layered system, with each layer fulfilling a specific role and working separately from others. This makes the API more secure and easier to update.
Since a REST API meets these standards, it can provide more security and efficiency.
What does the WordPress REST API do?
WordPress has its own REST API. This enables the platform to communicate with almost every other web application and website, regardless of the programming language they use.
With this API, a third-party app will be able to access your WordPress database and pull data from it. In fact, most WordPress plugins and themes use the platform’s REST API to function properly.
The WordPress REST API was released as part of the core software in version 4.7. Before then, it was only available as a plugin.
While the WordPress software is built with PHP, the REST API sends and receives data as JSON (JavaScript Object Notation) objects, which opens up new possibilities for developers.
What are the most common REST API commands?
REST APIs are designed to receive and respond to particular requests via HTML commands.
The most common commands you’ll use are:
- GET: You can use this command to fetch a particular resource from the server, like a post or piece of data.
- POST: This command lets you modify a resource on the server by adding code.
- PUT: With this command, you can edit a resource that’s already on the server.
- DELETE: This command removes a resource from the server.
These commands are followed by a line that gives more information about the request. These are known as endpoints.
For instance, if you wanted to retrieve a list of published posts on your site, you would use the following endpoint:
GET http://mysite.com/wp-json/wp/v2/posts/?status=publishedLet’s look at another example. If you want to add a new page, you would use the following command:
POST http://mysite.com/wp-json/wp/v2/posts/pageThere are many things you can do with these four commands. You can find a list of endpoints on the WordPress Developer Resources page.
Real-world examples of the WordPress REST API
Now that you have a basic understanding of how the WordPress REST API works, let’s look at some real-life examples, starting with WordPress.com.
The WordPress.com admin dashboard (called “Calypso”) is built entirely in JavaScript through the REST API.
Calypso is a web and desktop app that enables users to add new content, edit existing posts, and more. It uses the REST API to access the data on your WordPress.com site.
Another example is the Block Editor. In self-hosted WordPress, the Block Editor uses the REST API to interact with your database and create blocks.
Many online publications like USA Today also use the WordPress REST API. This enables them to automatically publish articles on other news apps, like Apple News.
How to enable and disable the REST API in WordPress
You don’t need to do anything to enable the REST API — it comes built into WordPress. Later in the post, we’ll show you how to access it.
While the REST API is a powerful tool for building apps with WordPress, it can make your site susceptible to Distributed Denial-of-Service (DDoS) attacks and malware. Plus, hackers might be able to access your data through the connection with other apps.
Disabling the WordPress REST API is not recommended. That’s because doing so can lead to issues with the Block Editor and any plugins on your site.
If you still want to go ahead and disable it, the easiest way to do this is with a plugin like WPCode.
Once you install and activate the plugin on your site, navigate to Code Snippets → Library in your WordPress dashboard.
Here, look for an option called Disable WordPress REST API. When you find it, hover over it and select Use snippet.
This will launch a page with a preview of the code.
If you scroll down to the Insertion box, you can select the Auto-Insert option so that the plugin will automatically apply this code to your site.
Then, scroll back to the top and move the toggle switch from Inactive to Active. Finally, click on Update to make these changes live.
How to use the WordPress REST API
Now, let’s look at how to use the WordPress REST API. We’ve already covered some examples above, but in this section we’ll show you exactly how to access and fetch data.
Step 1: Access the REST API
If you want to fetch data from a live WordPress site, you can access the REST API straight from your browser. All you have to do is enter the following address into the search bar (substituting in your own domain name and extension):
mysite.com/wp-json/wp/v2This will bring up the JSON file of your WordPress site.
You can then add elements to this URL to access specific data, as we’ll show you in the next step.
Step 2: Make requests to the REST API
As we mentioned earlier, you can use endpoints to access particular data on your site. If you want to retrieve a list of all your posts, simply add the endpoint /posts to your address:
mysite.com/wp-json/wp/v2/posts If you want to retrieve a specific post, you can just add its ID (you’ll find this on the Posts page in your WordPress dashboard):
mysite.com/wp-json/wp/v2/posts/4567Meanwhile, if you want to fetch data about your users, you would use the following request:
mysite.com/wp-json/wp/v2/usersThese are just simple examples, but there’s a lot more you can do. For instance, you can fetch posts that contain specific terms, change a post’s status from “draft” to “publish,” and more.
Step 3: Authenticate your requests
The WordPress REST API enables you to fetch any type of data on your website, but not all of it is publicly available. In some cases, you’ll need to authenticate your request.
To make authenticated requests to the WordPress REST API, you’ll first need to obtain an API key. To do this, navigate to Users → Profile in your WordPress dashboard.
Then, scroll down to the Application Passwords section. Here, you’ll need to enter a name for your password (for reference) and click on Add New Application Password.
This will generate an API key for you, which you’ll need to use in your requests. For instance, if your API key is “1234567890,” you can include it in an Authorization header like this:
https://mysite.com/wp-json/wp/v2/posts?Authorization=Bearer1234567890Remember to replace the code 1234567890 with the API key you’ve copied and remove any spaces.
You can also retrieve a list of posts written by a particular author, with their user ID. You can find their ID by going to the Users section in your WordPress dashboard and clicking on the author’s name. The ID will be displayed in the URL of their author page.
Let’s say an author’s name is “Joe” and their ID is “123.” In this scenario, you can use the following URL to retrieve a list of all posts written by Joe:
https://mysite.com/wp-json/wp/v2/posts?author=123&Authorization=Bearer1234567890If you can’t find the user’s ID, their profile might have been modified in such a way that the ID is no longer displayed. In this case, you can retrieve a list of all posts written by the user using their login name or email address instead of the ID.
To do this, you’ll have to use the “slug” parameter instead of the “author” parameter in your request:
https://mysite.com/wp-json/wp/v2/posts?slug=joe&Authorization=Bearer1234567890The “slug” parameter enables you to specify the user’s login name or email address. The WordPress REST API will return a list of all posts written by the user.
When to use the WordPress REST API
The WordPress REST API can be used for a wide range of projects. Here are a few examples:
- Integrating a WordPress site with a mobile app. If you’re a developer, you can use the REST API to retrieve and edit data on a WordPress site from a mobile app. This enables you to build custom apps that interact with your site.
- Creating custom integrations. Using the WordPress REST API, you can create custom integrations with other software like CRM tools.
- Building custom scripts. You can use the REST API to automate certain tasks on your WordPress site, like scheduling posts or updating user profiles.
As you can see, the REST API enables you to integrate WordPress with apps or sites built on other platforms.
When not to use the WordPress REST API
While the WordPress REST API can be a powerful tool, it may not always be the right one for your project. Let’s look at a few reasons why you might not want to use it.
As you may recall, the WordPress REST API is built with JavaScript. Therefore, if you’re developing an app that doesn’t support JavaScript, it won’t function properly if you’re using the REST API.
Additionally, apps built on JavaScript may not be very accessible. For instance, the way it renders dynamic content may be incompatible with screen readers. As a result, it could make your content inaccessible to users with visual impairments.
How to secure the WordPress REST API from exploits
As mentioned earlier, using the WordPress REST API can make your site vulnerable to threats. The API acts as a bridge between two platforms, and hackers may find a way into your website through this connection.
As such, before you start using the WordPress REST API, it’s important to create a backup of your WordPress site. This way, if something goes wrong, you can restore a recent version of your content.
Additionally, you’ll want to make sure that you have sufficient security measures in place. This means using a tool like Jetpack Protect.
This plugin comes packed with security features, including malware scanning, vulnerability scanning, and a web application firewall (WAF).
Furthermore, it’s a good idea to use the REST API on a WordPress staging site before making your changes live. This way, if you accidentally break your website, it won’t affect the user experience on the front end.
How to fix common REST API errors and issues
You may run into some errors when using the WordPress REST API. So, let’s look at some of the most common issues and the steps you can take to resolve them.
Slow response times and timeouts
When calling the WordPress REST API, you may encounter slow response times and timeouts. These issues are usually caused by the following factors:
- Insufficient server resources. Your server might not have enough resources to handle requests made through the REST API. In this case, you’ll need to upgrade to a more powerful WordPress hosting plan.
- Plugin or theme conflicts. WordPress plugins and themes can sometimes conflict with the REST API. When this happens, try disabling all plugins and switching to a default theme to see if this resolves the issue. If it does, you can reactivate your plugins one at a time to identify the culprit.
- Size of data. Large data transfers during API calls can cause timeouts. To prevent this, you can try reducing the number of items displayed per page (we’ll show you how to do this later in the post).
- Database issues. If your WordPress database is not optimized, it can lead to slow response times and timeouts when calling the REST API. You can optimize it by removing unnecessary data and installing an optimization plugin.
Additionally, you may want to track the performance of your API with a tool like Google Cloud’s operations suite (formerly Stackdriver) and Microsoft’s Application Insights. These tools can provide insight into the performance of the WordPress REST API and help you identify the causes of slow response times.
403 Forbidden error when calling the REST API
The 403 Forbidden error is an HTTP status code indicating that the client is not authorized to access the requested resource. Let’s look at some common causes of this error and potential solutions:
- Incorrect API Key. If the request requires an API key, make sure that the key you’re using is valid and that it’s being passed in the request headers correctly.
- Invalid nonce. A ‘nonce’ is a random number used once to prevent request forgery. If it’s invalid, it may result in a 403 forbidden error.
- User permissions. You’ll also want to make sure that you have the necessary permissions to access a specific API endpoint. If you’re not the owner of the website, you may need to ask the administrator to give you the right permissions.
- Security plugins. Security plugins can block an API call because it sees it as a security threat. You can whitelist the API endpoint in your plugin settings to resolve this type of issue.
- Firewall. You might be using a firewall that’s blocking the API request. Make sure that the firewall is set up correctly, or try to disable it while using the API.
- Server configuration. Some servers are not configured to handle certain API calls, so you might want to reach out to your hosting provider for assistance.
You can also use your browser’s developer tools to inspect the network requests and request headers. If you use Chrome, simply press Ctrl+Shift+C to open DevTools.
Additionally, you can check your server logs for more information about the error. You should be able to access them through your hosting account. If not, you can ask your hosting provider for help.
REST API encountered an unexpected result
The “REST API encountered an unexpected result” error is a common issue. It’s typically caused by the following factors:
- Permissions. You might not have the right permissions to access the requested resource. If that’s the case, you’ll need to contact the site’s administrator.
- URL configuration issue. This error can occur if the API endpoint URL is configured incorrectly. Double-check the URL to ensure that it is correct and that all necessary query parameters are included.
- Incorrect command. You may be using the wrong command (e.g. GET, POST, PUT, DELETE) for the request. Check the API documentation to make sure that you’re using the correct command for the specific endpoint.
- Incorrect request format. Make sure that you’re using the right format in your request. In the WordPress REST API, data must be sent as JSON.
- Wrong endpoint. You might be trying to call an endpoint that doesn’t exist. In this scenario, double-check the endpoint URL to make sure it’s correct.
- Server-side issues. Your server might be experiencing issues. This is more common with shared hosting plans. If this happens to you, it may be time to upgrade to a server with more resources.
You may also want to disable your plugins to see if the issue is resolved. As mentioned earlier, some tools may cause compatibility issues with the WordPress REST API.
rest_api_init not working
The “rest_api_init not working” error is another common WordPress REST API error. It’s usually caused by plugin and theme conflicts, as well as limited server resources.
Still, there are other factors that can lead to the WordPress REST API not working, like:
- Custom REST API endpoints. If you’re making requests with custom endpoints, make sure that you’re using the correct hooks and functions.
- .htaccess file. You may need to check your .htaccess file to ensure that it’s set up correctly.
- CORS error. If you’re trying to make Cross-Origin Requests (CORS) and the WordPress REST API is not working, it might be that the server is not configured to accept them. You may want to contact your hosting provider to see if the server accepts CORS.
Additionally, you could be using an old WordPress installation that doesn’t support the API. If so, it’s important that you upgrade to the latest version.
Basic authentication not working
The “Basic authentication not working” error may occur when trying to call the WordPress REST API using Basic Authentication. Basic Authentication is a simple authentication scheme built into the HTTP protocol. It utilizes a username and password to authenticate someone.
Here are some common causes of this error (and how to resolve them):
- Incorrect credentials. Check the username and password in the request headers to ensure that they’re correct.
- Secure Sockets Layer (SSL) issue. Make sure that you have a valid SSL certificate installed and that it’s configured correctly. If it isn’t, take a look at our step-by-step guide on how to get a free and valid SSL certificate.
- HTTP to HTTPS redirects. Some websites are configured to redirect HTTP requests to HTTPS. If the browser is trying to authenticate on HTTP, you might run into this error. Therefore, you’ll want to make sure that you’re running a request on an HTTPS endpoint.
Like other REST API issues, this error can also be caused by theme and plugin conflicts. Once again, you’ll want to switch to a default theme and deactivate your plugins to troubleshoot the issue.
If that doesn’t help, you might want to disable your firewall temporarily. This could be blocking your authentication request.
If you’re making a CORS, your server may not be configured to accept them. It’s worth checking with your hosting provider to see if there’s anything they can do on their end.
Finally, if you’re not the admin of the site, you may not have the correct permissions or role to complete the request. In this case, you’ll need to reach out to the owner of the website.
Advanced use cases of the REST API
Thanks to the WordPress REST API, you can retrieve data from your site using popular frameworks and other programming languages. Let’s take a look at a few examples.
How to use the WordPress REST API with React
React is a popular JavaScript library for building user interfaces. You can use the Node-WPAPI client to make HTTP requests to the WordPress REST API.
For instance, to retrieve a list of posts on your WordPress site, you would need to enter the following into Node-WPAPI:
import WPAPI from 'wpapi';
const wp = new WPAPI({ endpoint: 'http://example.com/wp-json' });
wp.posts().then(posts => {
console.log(posts);
});For more information on using the WordPress REST API with React, you can check out the Node-WPAPI documentation.
How to use the WP REST API with Angular
Angular is a JavaScript framework for developing web applications. To use it with the WordPress REST API, you’ll need to use the @angular/common/http module.
For instance, you can input the following code to retrieve a list of posts:
import { HttpClient } from '@angular/common/http';
@Injectable()
export class PostService {
constructor(private http: HttpClient) {}
getPosts(): Observable<any> {
return this.http.get('http://mysite.com/wp-json/wp/v2/posts');
}
}You can check out the Angular documentation for more information on using its HttpClient to make requests to the WordPress REST API.
How to use the WordPress REST API with Python
You can also use the WordPress REST API with Python. This is a popular programming language that can be used to build web applications and other software.
To get started, you’ll need to use the Requests library. If you wanted to fetch a list of your WordPress posts, you would enter the following:
import requests
response = requests.get('http://example.com/wp-json/wp/v2/posts')
posts = response.json()
print(posts)You can read the Requests library documentation for more detailed instructions.
How does the REST API compare to other WordPress API solutions?
You may be wondering how the REST API differs from other WordPress API solutions. To give you an idea, we’re going to compare it to some of the most popular alternatives.
WordPress REST API vs. AJAX
The WordPress REST API provides an efficient way to access WordPress data. It enables developers to build custom applications and integrations with WordPress.
Meanwhile, the WordPress AJAX API is an older method of accessing WordPress data. It was introduced in WordPress 2.0 and enables developers to make asynchronous requests from the front end of the site, using JavaScript.
The WordPress AJAX API can be a bit restrictive in terms of functionality, so it’s not recommended for use in complex projects.
WordPress REST API vs. WPGraphQL
WPGraphQL is a GraphQL implementation for WordPress that provides an alternate way to access WordPress data. GraphQL is a query language for your API. It enables clients to request exactly the data they need, and nothing more.
Unlike the WordPress REST API, WPGraphQL requires a separate application password to be generated for each user who needs access. Plus, it can be a bit slow in delivering content because it uses a more complex query language.
WordPress REST API vs. XML-RPC
Introduced in WordPress 1.5, the WordPress XML-RPC API enables you to make remote requests to WordPress using the XML-RPC protocol.
XML-RPC is simple and lightweight, and can therefore deliver results faster. The problem is, that like Ajax, it has limited functionality compared to the WordPress REST API.
Frequently asked questions about the WordPress REST API
In this guide, we’ve covered most of the essentials when it comes to the WordPress REST API. But, just in case, let’s look at a few frequently asked questions regarding this powerful tool.
Does the WordPress REST API have a return limit?
By default, the WordPress REST API has a maximum return limit of 100 items per page. That means, if you make a request to an endpoint that returns a list of items (like posts, pages, or users), the API will only display a maximum of 100 items in the response.
Fortunately, you can use the “per_page” parameter to increase the limit to a maximum of 500 items per page.
For example, if you want 200 items per page, you can use the following:
https://mysite.com/wp-json/wp/v2/posts?per_page=200Keep in mind that you can also decrease the number of items displayed per page.
Can I use the REST API with WooCommerce?
WooCommerce has its own REST API. The WooCommerce REST API enables you to access and modify data from your WooCommerce store. This includes information on products, orders, and customers. Plus, you can use the WooCommerce REST API to integrate WooCommerce with other ecommerce platforms.
Get started with the WordPress REST API
The WordPress REST API enables you to integrate your site with other apps and third-party tools. Web developers can use it to fetch data for single-page applications, connect WordPress to a mobile app, and much more.
Additionally, you can use the WordPress REST API with other frameworks and programming languages, including React, Angular, and Python. Although the WordPress REST API is a powerful and dependable tool, it’s still important to back up your site and use a security tool to prevent attacks through these connections.
With Jetpack Protect, you can secure your WordPress site against malware and hackers, and use the WordPress REST API in a safer environment.
Jetpack 