Think of how much of your business data you store in WordPress. What if you could access it and use it in different applications? Thankfully, you can do that with the REST API in WordPress.
The REST API expands the power of WordPress beyond your website. Advanced developers can use the API to connect WordPress with other sites and applications.
This post is your introduction to the WordPress API and how you could use it.
About APIs
Let’s start with some basics. What does API stand for? An API is an Application Programming Interface. An API allows two applications to communicate with one another.
APIs are the backbone of the modern internet. You probably use hundreds of APIs without realizing it. Companies often create APIs to encourage developers to use their services on their sites and applications. A common example is the Google Maps API, which allows developers to embed maps with the full Google Maps functionality into their sites.
What is a REST API?
A Representational State Transfer, or REST, API complies with a set of standards that allow two different systems to work together. Without the REST protocols, the systems wouldn’t be compatible.
5 essential elements to make an API ‘RESTful’:
- Client-Server Architecture. The client and server applications have to be separate to promote independent development. The server side is the platform the API belongs to, in this case, WordPress. The client is the application trying to connect to the platform. As the server-side technology evolves, the client-side application still needs to be able to access it using the same methods.
- Uniform Interface. Every part of the API needs to function using the same interface, language, and methods. For example, the URLs used to access resources must be consistent and uniform.
- Stateless Protocol. REST APIs require the use of a stateless protocol. The client request provides all the data upfront, and the server response should include everything the client needs. Nothing about the request should be stored on the server. This approach reduces memory utilization and error potential.
- Caching. A RESTful API uses cacheable data for better efficiency and speed.
- Layered System. Developers build REST APIs using layers. The layers can interact, but they’re separate with their own functions. This layered approach makes it easier to update the API while also improving security.
The key takeaways to these RESTful protocols are that WordPress allows you to interface with your site without compromising security, privacy, or performance by enabling a REST API. The REST API also adopts a common internet standard, making it easier for developers to access the API without learning something new.
About the WordPress REST API
The REST API in WordPress started as a plugin to add functionality to the platform. The API was fully integrated into the core WordPress software with Version 4.7 in 2016.
While originally intended and still widely used to enable separate applications to connect to your WordPress site, the REST API plays a key role in many recent WordPress advancements. The REST API in WordPress is the foundation of the new Block Editor. Many theme, plugin, and custom application developers are using the REST API to manage and publish WordPress content.
What Do I Need to Know to Use the WordPress REST API?
To take advantage of the REST API in WordPress, you must be familiar with HTTP request methods and JSON.
WordPress uses JSON or JavaScript Object Notation as the format for exchanging data in the REST API.
The Basics of the WordPress REST API
At the most basic level, an API processes a request that returns a response. The client (the app you built) asks the server (WordPress) to do something, and the API makes it happen.
Basic HTTP request methods used in the WordPress REST API are:
- GET. Use this command to retrieve something from WordPress, like a particular piece of data.
- POST. This command adds a resource to WordPress, like creating a post.
- PUT. This command enables you to edit or update an existing resource on the server.
- DELETE. Use this command to remove something from WordPress.
The actual API interactions are a bit more complicated and involve these basic elements.
Key Concepts of the WordPress REST API
Your API response cycle will include these basic elements:
- Routes and Endpoints. Routes are URLs you enter to make a request. The endpoint combines a URL with an HTTP method.
- Requests. A submitted endpoint makes a request to the server.
- Responses. If you submitted a properly configured endpoint, you’ll receive a response with the data you requested in JSON format.
- Schema. The schema is the properties and input parameters the WordPress REST API accepts and returns.
- Controller Classes. Think of the controller classes as the instructions for how you want the request to be handled. Controller classes manage and coordinate all the moving parts of an API response cycle.
For a more in-depth look at exactly how the WordPress REST API works and all the available options, read the REST API Handbook from WordPress’ Developer Resources.
Is the WordPress REST API Secure?
At first glance, you may wonder if anyone can access your site and start deleting posts via the API. Fortunately, any API requests that perform changes or access sensitive data require authentication.
The WordPress REST API Handbook puts it this way:
“The REST API is a developer-oriented feature of WordPress. It provides data access to the content of your site, and implements the same authentication restrictions — content that is public on your site is generally publicly accessible via the REST API, while private content, password-protected content, internal users, custom post types, and metadata is only available with authentication or if you specifically set it to be so.”
Why the REST API Matters for WordPress Developers
Not everyone loves PHP or the WordPress development libraries. With the REST API, developers are no longer constrained. The API opens up WordPress development for people who don’t like or are still learning PHP.
WordPress is an excellent content management system. It’s simple for even technical novices to input content into the system. The REST API allows developers to access all that content and display and use it in new and interesting ways. It’s the best of both worlds. You get a system that’s easy for clients to input content into, and you get even more options for how to build great experiences. The main selling point for the REST API is that it should lead to faster and simpler development.
How to Access and Use the WordPress API
The WordPress REST API is enabled by default for all WordPress sites. Many WordPress features, such as the editor, work off of the API, so it’s not something you would want to disable.
You can access the API through a browser to get an idea of how it works.
Go to example.com/wp-json/wp/v2/posts
You’ll see a list of all your posts.
This type of basic HTTP request is what you’d send using an application. You can also interact with the API using the WordPress command line interface.
Client Libraries
Client libraries make it easy to connect an external application to the WordPress API using the programming language of your choice.
- JavaScript. The Backbone.js client is part of WordPress core. Other options include node-wpapi and ember-wordpress.
- Ruby. The read-only wp-api-client was written in Ruby.
- C# / .NET. For the C# fants out there, you can use WordPress PCL.
A word of caution: Only Backbone.js is officially recommended and maintained by WordPress.
Built-In Routes and Endpoints
The API allows authenticated or logged-in users to complete most content management functions you can do inside the WordPress admin. You need to know the right route and endpoint.
| Resource | Base Route |
| Block Directory Items | example.com/wp-json/wp/v2/block-directory/search |
| Block Renderer | example.com/wp-json/wp/v2/block-renderer |
| Block Revisions | example.com/wp-json/wp/v2/blocks/<id>/autosaves/ |
| Block Types | example.com/wp-json/wp/v2/block-types |
| Blocks | example.com/wp-json/wp/v2/blocks |
| Categories | example.com/wp-json/wp/v2/categories |
| Comments | example.com/wp-json/wp/v2/comments |
| Media | example.com/wp-json/wp/v2/media |
| Page Revisions | example.com/wp-json/wp/v2/pages/<id>/revisions |
| Pages | example.com/wp-json/wp/v2/pages |
| Plugins | example.com/wp-json/wp/v2/plugins |
| Post Revisions | example.com/wp-json/wp/v2/posts/<id>/revisions |
| Post Statuses | example.com/wp-json/wp/v2/statuses |
| Post Types | example.com/wp-json/wp/v2/types |
| Posts | example.com/wp-json/wp/v2/posts |
| Search | example.com/wp-json/wp/v2/search |
| Settings | example.com/wp-json/wp/v2/settings |
| Tags | example.com/wp-json/wp/v2/tags |
| Taxonomies | example.com/wp-json/wp/v2/taxonomies |
| Themes | example.com/wp-json/wp/v2/themes |
| Users | example.com/wp-json/wp/v2/users |
WordPress API Example Requests
Most developers will work with posts, so let’s look at some examples of what you can do with posts through the API. We’ll show the example requests as a curl command you’d use in the CLI.
Updating an Existing Post
curl -X POST https://example.com/wp-json/wp/v2/posts/<id> -d '{"title":"New Post Title"}'You’d put the ID number that comes after /posts/ so the system knows which post you want to modify, and what’s between the brackets is the change we want to make. In addition to updating the content, you could also change the status of a post.
Finding a Post
The updating a post feature is only helpful if you know the post ID you want to edit. To view a list of all your posts, you’d use this request.
curl https://example.com/wp-json/wp/v2/postsYou can add filters to narrow the list down by searching for a particular author, dates, and other variables.
Best Practices for Working with the WordPress API
Global Parameters
Global Parameters apply to every resource and control how the API handles the request. They are:
- _fields
- _embed
- _method (or X-HTTP-Method-Override header)
- _envelope
- _jsonp
The API documentation spells out how to use each one. One of the most common use cases is using the _fields parameter to narrow down which fields are included in the response. For example, if you wanted to display a list of posts but not the full content, you could query for just the post title and permalink. If you don’t specify, it will return every piece of data about the post. This is one way using global parameters can lead to faster and more efficient responses.
Permissions and Authentication
You can create a specific authentication password to include with your API requests. Go to your user profile in the WordPress Admin and go to the section called Application Passwords.
Give your Application Password a name and click Add New Application Password.
Security Considerations: Protecting Data and Resources
Hackers can exploit the REST API to gain access to your website. To keep your site secure, follow these best practices:
- Regularly back up your site.
- Use a Web Application Firewall (WAF).
- Install a security plugin like Jetpack.
Custom Routes and Endpoints
The REST API is so powerful because of how you can customize it to anything you want to build. The default routes and endpoints cover most of the use cases, but WordPress also includes a way for users to build their own routes and endpoints. Check out this documentation for examples of how to go about building your own custom routes.
Replacing Admin AJAX Requests
AJAX was introduced in WordPress 2.0 and was the primary way of accessing WordPress data. But it has its limitations and can sometimes slow down your site. Replacing heavy AJAX requests with the REST API can improve site performance.
Common Challenges and Errors with the REST API
When beginning to use the REST API, you may encounter some of these common issues.
Performance Optimization
If you’re getting slow responses or timeouts, start by looking at your server. You need a robust hosting plan, like Pressable’s managed WordPress hosting. You also should look for any plugin and theme conflicts. Finally, the size of the request or an unoptimized database could slow down your API responses.
Adding caching for REST API responses is another way to solve speed issues.
403 Forbidden Error: Unauthorized Access
You didn’t have the right access if you get a 403 error as a response to a request. It could mean you’re not using the API key or password correctly in the header. Firewalls or security plugins also could block access to a resource.
Start by double-checking your authentication method and then check your plugin and firewall settings.
What Can I Do with the WordPress REST API
The possibilities are endless with this API. Let’s look at some of the ways you could use the REST API.
Add External Data to Your Site
You can retrieve and add data to your WordPress site using the API. For example, a media company could pull updates from a Slack channel to create a live blog of all their reporters working on a big story, such as election night.
Use Your WordPress Content in an External Application
You also can use the API to display your WordPress data in another application. One of the most common uses of the REST API in WordPress is to pull out site content to use in a mobile app.
Create Easier Ways to Manage Your Site
The API also allows you to create new ways to manage your site. The most notable example is WordPress.com’s Calypso project.
The Calypso project is a reinvention of the WordPress Dashboard (WP-ADMIN). Calypso allows a user to centrally manage multiple WordPress sites and create content within a mobile-friendly user interface. It also loads significantly faster. You can read all about the story of Calypso. The creation of Calypso also allowed for the creation of a WordPress desktop app available on MacOS/Windows/Linux.
Build New Interfaces for Editing Content
You also can use the API inside WordPress to create more intuitive interfaces for editing and managing content. For example, the API powers the new block editing features as well as many plugins. Understanding how the API works would be helpful if you want to create custom Gutenberg blocks.
For a taste of how the REST API changed the game with block editing, download our e-book on the basics of Full Site Editing. The e-book walks you through how to accomplish several common tasks only using blocks. This change in how to edit and manage WordPress sites wouldn’t be possible without the REST API.
But if you want someone to add content to your site without giving them full access to WordPress, you could use the API to create a custom editing interface that only included the fields and post types you wanted them to fill out.
Build New Front-End Presentations
The REST API enables creative and flexible ways to present content on your WordPress website. Theme developers may find it easier to rely on the API instead of PHP.
What Other APIs Does WordPress Offer?
The REST API is just one of many APIs WordPress provides. The REST API is the most robust and allows you the most flexibility in how you use it. The rest of the WordPress APIs are primarily used in plugin development, but they’re still an option to consider, depending on what you’re building. You can learn more about the other available APIs on the WordPress Codex site.
If you run an eCommerce store using WooCommerce, you can use the WooCommerce REST API.
Do I Need to Use the REST API in WordPress?
No, you don’t have to use the REST API, but you probably already are. The API is the basis for so many new features and plugins that you’re likely taking advantage of it on your site without realizing it.
As to whether you should start building your own applications or projects using the API, that’s a matter of personal preference and comfort level with the technology.
Use the REST API when you want to use a language other than PHP or are worried about performance issues.
Use the REST API When You Don’t Want to Use PHP
If you want to write a theme, plugin, or external application as a client-side JavaScript application or standalone program in any language besides PHP, use the WordPress REST API to access content with your WordPress site.
Use the REST API for Better Performance
Using the new WordPress REST API allows developers to create cutting-edge new features without using a ton of server-side resources. That means most features developed using the REST API will be faster than if developed using PHP. It also means you can deliver remarkable user experiences without adding expensive infrastructure.
The REST API also allows you to more easily adopt a headless approach. You can separate front-end and back-end and connect via the API for more efficient development and better scaling.
WordPress API Tools and Resources
If you want to learn more about how to take advantage of the WordPress REST API, check out these resources:
- WordPress REST API Handbook
- Using WP-CLI on Pressable
- Tutorial: Using the WordPress REST API
- Tutorial: Interacting with the WordPress REST API
Optimal Site Performance with the REST API in WordPress and Pressable
We’re excited about what the REST API is doing for WordPress. It means there will be a lot of new features that will be faster and more sophisticated. It also means you can add more advanced, engaging, and immersive user experiences to a WordPress site, all without a major sacrifice to site performance.
At Pressable, we’ve dedicated a lot of resources and our engineers’ brainpower to ensure our clients never have to sacrifice site performance.
We utilize non-volatile memory express (NVMe) servers with improved response times, enhanced queuing, and optimal security. Your site runs faster and safer and will rank better in search engines.
The NVMe server infrastructure is about 10 times faster than the standard SSD technology used by most other hosting companies. You can trust our servers to respond quickly and scale effortlessly, no matter what you build or what method you built it with.
We also make it easier to test out and learn the WordPress REST API. From WP-CLI support to free staging sites, Pressable includes the developer-friendly features and support you need from a hosting service.
Sign up for a demo to learn more about why Pressable is the best choice for WordPress developers.
Obatarhe Otughwor
Obatarhe is a WordPress enthusiast, a community volunteer, and a tech advocate. He is dedicated to providing exceptional support that exceeds expectations, consistently earning him 5-star ratings from customers. His approach involves understanding each customer's unique needs and delivering tailored solutions that effectively resolve their issues. With a background as a product expert for Google, Obatarhe possesses extensive technical experience gained from working remotely across diverse areas of computing, including technical support and basic programming with PHP, Laravel, HTML/CSS, and JavaScript. His years of experience have honed his ability to delight customers with his skills and expertise. When he's not working, you can find him traveling and taking beautiful landscape pictures.
