WordPress REST API: What It Is and How to Get Started Using It

In this comprehensive guide, we’ll walk you through all the basics you need to know. We’ll explain what APIs are in general, and what REST APIs (and the WordPress-specific version) are in particular. Then, we’ll talk about how to start using the REST API yourself. Let’s jump right in!

📚 Table of contents:

• An introduction to Application Programming Interfaces (APIs)
• The fundamental rules of a REST (Representational State Transfer) API
• The WordPress REST API
• The anatomy of a WordPress REST API request
• How to start using the WordPress REST API
• How to disable the REST API in WordPress
• One more approach at using the WordPress REST API
• Conclusion

An introduction to Application Programming Interfaces (APIs)

Before we delve into the WordPress REST API specifically, let’s back up a little. To understand this concept, it’s important to first have a basic idea of what APIs are in general.

At its most fundamental level, an API – or Application Programming Interface – enables two applications to communicate with one another. For instance, when you visit a website, your browser sends a request to the server where that site is located. That server’s API is what receives your browser’s request, interprets it, and sends back all the data required to display your site.

There’s a lot more to the way APIs work in a technical sense, of course. However, we’re going to focus on what probably matters most to you – the practical applications. APIs have been getting lots of attention and visibility, because many companies have begun to package them up and provide them as products you can use.

In other words, developers at a company like Google will collect some parts of their application’s code together, and make it publicly available. That way, other developers can use the API as a tool to help their own sites connect to Google and take advantage of its features:

For instance, you could use the Google Maps API to place a fully-functioning map on your site that benefits from all of Google’s relevant data and features. This saves you from having to code up a map and collect all that data yourself. The same applies to a wide range of sites and applications.

As websites and the functionality they rely on get more complex, tools like APIs become crucial. They enable developers to build on existing functionality, making it possible to simply ‘plug in’ new features to your website. In turn, the site that owns the API benefits from the increased exposure and traffic.

The fundamental rules of a REST (Representational State Transfer) API

There are many ways to create an API. A REST (Representational State Transfer) API is a particular type that is developed following specific rules. In other words, REST presents a set of guidelines developers can use when building APIs. This ensures that the APIs function effectively.

To understand how REST APIs work, you’ll need to know what rules (or ‘constraints’) they function under. There are five basic elements that make an API ‘RESTful’. Keep in mind that the ‘server’ is the platform the API belongs to, and the ‘client’ is the site, application, or software connecting to that platform:

1. Client-server architecture. The API should be built so that the client and the server remain separate from one another. That way they can continue to develop on their own, and can be used independently.
2. Statelessness. REST APIs must follow a ‘stateless’ protocol. In other words, they can’t store any information about the client on the server. The client’s request should include all the necessary data upfront, and the response should provide everything the client needs. This makes each interaction a ‘one and done’ deal, and reduces both memory requirements and the potential for errors.
3. Cacheability. A ‘cache’ is the temporary storage of specific data, so it can be retrieved and sent faster. RESTful APIs make use of cacheable data whenever possible, to improve speed and efficiency. In addition, the API needs to let the client know if each piece of data can and should be cached.
4. Layered system. Well-designed REST APIs are built using layers, each one with its own designated functionality. These layers interact but remain separate. This makes the API easier to modify and update over time, and also improves its security.
5. Uniform interface. All parts of a REST API need to function via the same interface, and communicate using the same languages. This interface should be designed specifically for the API and able to evolve on its own. It should not be dependent on the server or client to function.

Any API that follows these principles can be considered RESTful. There is also a sixth constraint, referred to as ‘code on demand’. When followed, this technique lets the API instruct the server to transmit code to a client, in order to extend its functionality. However, this constraint is optional, and not adopted by all REST APIs.

You may also be interested in:

• How to Add Contact Forms to a Static WordPress Site for Free
• 15 Best Programming Fonts for Coding and Development (Free!)
• 5 High-Quality Sketch Alternatives for Windows

The WordPress REST API

At this point, you may be wondering how all of this affects you. APIs are excellent tools, but are they relevant to your day-to-day work? If you’re a WordPress user, the answer is “yes”.

The WordPress REST API has been under development for a couple of years now. For quite a while, it was worked on as an independent plugin, which was available for anyone to experiment with.

In fact, there were two separate versions of the WordPress REST API plugin. Elements of the API were added to the core platform as early as update 4.4. This was followed by it becoming fully integrated as of WordPress 4.7 (in 2016). This means that today, WordPress has its own fully-functional REST API.

This opens up numerous possibilities for developers. It also makes WordPress more flexible and universal than ever. As Katie Keith, the Operations Director at Barn2 Media puts it:

Since its implementation, the WordPress REST API has become a critical component of the Content Management System (CMS). It’s no longer only used by external services, and a lot of plugins, themes, and the Block Editor itself rely on the REST API to function. If you’re wondering how to disable the REST API, we recommend against it, but we’ll show you how to do it safely further on in the article.

It’s also important to note that you may hear this feature sometimes referred to as the WordPress JSON REST API. The ‘JSON’ part, which stands for JavaScript Object Notation, describes the format this API uses to exchange data. That format is based on JavaScript, and is a popular way of developing APIs thanks to how well it interfaces with many common programming languages. In other words, a JSON API is able to more easily facilitate communications between applications that utilize different languages.

The anatomy of a WordPress REST API request

There are some basic concepts you’ll need to understand if you want to get hands-on and start experimenting with the API yourself.

As we’ve explained, every API processes requests and returns responses. In other words, a client asks it to perform a certain action, and the API carries out that action. Exactly how APIs do this can vary. REST APIs are specifically designed to receive and respond to a particular type of request, using simple HTML commands (or ‘methods’).

To illustrate, here are the most basic and important HTML methods a client may send:

• GET: This command retrieves a resource from the server (such as a particular piece of data).
• POST: With this, the client adds a resource to the server.
• PUT: You can use this to edit or update a resource that’s already on the server.
• DELETE: As the name suggests, this removes a resource from the server.

POST /foldername/my_file.php

The /foldername/my_file.php part is called the ‘route’, since it tells the API where to go and what data to interact with. When you combine it with the HTTP method (POST in this case), the entire function is referred to as an ‘endpoint’.

Most REST APIs and the clients that interact with them get a lot more complicated than this – WordPress’ version included. However, these essential elements form the basis for how the REST API works.

How to start using the REST API in WordPress

As long as you have a WordPress site set up, you can start experimenting with the REST API right away. You can perform various GET requests to retrieve data directly, simply by using your browser.

To access the REST API in WordPress, you’ll need to start with the following route:

yoursite.com/wp-json/wp/v2

Then, you can add onto this URL to access various types of data. For instance, you could look up a specific user profile via a route like this:

yoursite.com/wp-json/wp/v2/users/4567

In this scenario, “4567” is the unique user ID for the profile you want to see. If you left out that ID, you would instead see a list of all the users on your site:

You can use the same basic route to view other types of data, such as your posts or pages. You can even search for subsets of the data that meet certain criteria. For example, you could retrieve all posts that include a specific term using this URL:

yoursite.com/wp-json/wp/v2/posts?=search[keyword]

This is just a simple illustration, of course. There’s almost no limit to what you can actually do using the REST API. If you want to learn more about how it works, we recommend starting with the following resources:

• The REST API Handbook. This is an official WordPress resource that documents all sorts of information about the REST API. Among other things, you’ll find a list of endpoints you can use, as well as details on some of the REST API’s structural aspects that we haven’t touched on here.
• W3Schools tutorials. While this resource isn’t REST API-specific, it offers handy tutorials that can help you brush up on key concepts, such as HTTP methods and JSON.
• The Ultimate Guide to the WordPress REST API. This free e-book from WP Engine contains lots of practical information and examples. Plus, it will walk you through how to accomplish several basic (and more advanced) tasks.
• While we’re at it, you can also check out this list of the top 10 plugins for WordPress developers. It will surely come in handy as you’re exploring the world of REST API.

The WordPress REST API is no doubt a complex topic. Even for non-developers, it’s worthwhile to understand the basics of how this technology works, and what it makes possible. What’s more, it may even enable you to start dabbling in development yourself!

How to disable the REST API in WordPress

The WordPress REST API can be an amazing tool if you need to connect other services and apps to your site. However, it can also lead to security vulnerabilities. Attackers might be able to access critical data through this connection.

We don’t recommend fully disabling the REST API, as it can lead to issues with key features on your site. Since its implementation, the REST API has become an intrinsic WordPress component. Most plugins use it to interact with the CMS. Moreover, the Block Editor relies on the REST API for editing content.

Although disabling the REST API is not a good idea, you can partially block access to specific resources for security purposes. The easiest way to do this is by using a plugin, like Disable REST API:

This plugin gives you full control over what routes users can access depending on their roles and authentication status. Once you install and activate it, you can navigate to Settings > Disable REST API and choose which users to configure rules for:

After you select a user role, you can scroll down and enable the API routes you want them to access. By default, every route will be disabled for unauthenticated users. Other roles, such as editors, will have almost full API access:

For security purposes, only the administrator role should have full REST API access. For every other role, we recommend that you disable access for the resources they don’t explicitly need to use.

One more approach to using the WordPress REST API

The REST API can be used for a number of interesting things and projects. We’ve established that pretty clearly.

There’s one area, however, where it’s been getting some real popularity:

Headless WordPress is the idea of decoupling the two main layers of the WordPress ecosystem – the backend and the frontend.

This allows you to take all the goodies that the WordPress software has under the hood and connect them with a final product that doesn’t use the standard WordPress presentation – it is not a website, per se.

The whole concept is very interesting. We talk about it some more in another post, where we discuss whether headless WordPress makes sense, and compare the top headless WordPress hosting solutions in the market.

Conclusion

There’s no better time to learn about the WordPress REST API than now. Since it’s been fully merged into WordPress core, it’s going to play an important role in the platform’s future. Developers of all stripes will be using this API to connect WordPress to the broader web in ways that were previously difficult or impossible.

Understanding this concept for yourself can be a bit challenging. At a basic level, however, the concepts are easy enough to grasp. A REST API is an interface that enables two programs to ‘talk’ to one another and is created by following guidelines that ensure it’s flexible, extensible, and secure. If you want to delve deeper into how all of this works and how it can be used, there are lots of helpful resources out there, such as the official handbook.

Further reading:

• Change the way your WordPress site works with functions
• How to retrieve any post you want with WP_Query
• How to automate WordPress development workflow
• Productivity tools for designers and WordPress users
• WordPress.com vs WordPress.org
• How to adapt Your plugin for Gutenberg: Part 1 (Block API)
• How to make your plugin compatible with Gutenberg: Part 2 (Sidebar API)
• Fetch API for beginners
• Google Maps JavaScript API

Do you have any questions about the REST API, and what it means for WordPress? Ask us in the comments section below!

Layout and presentation by Karol K.