if you’ve spent any time building WordPress sites over the past few years, chances are you’ve heard reference made to the new REST API. However, unless you’re an experienced developer, you may not have any idea what the WordPress REST API actually is.
While the technical details are a bit complex, the basic concepts behind this feature are easy enough to grasp. The new API helps expand what WordPress as a platform can do. What’s more, the REST API makes it simpler than ever for developers to connect WordPress with other sites and applications.
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 WordPress REST API yourself. Let’s jump right in!
An introduction to Application Programming Interfaces (APIs)
Before we delve into the REST API specifically, let’s back up a little. To understand this concept, it’s key 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 therefore 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:
- 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.
- 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.
- 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.
- 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.
- 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.
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 unequivocally “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 developers could contribute to over time was available for anyone to experiment with.
In fact, there were two separate versions of the REST API plugin. Elements of the API were added into 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.
Why did the platform make this move? According to the project site itself, it’s because WordPress is moving towards becoming a “fully-fledged application framework”.
In other words, the REST API enables the platform to interact with just about any site and web application. Plus, it can communicate and exchange data regardless of what languages an external program uses.
This opens up numerous possibilities for developers. It also makes WordPress as a platform more flexible and universal than ever. As Katie Keith, the Operations Director at Barn2 Media puts it:By understanding the REST API, WordPress developers can choose the most effective way to implement each task, without being confined to specific technologies or platforms such as PHP or the WordPress back end. Used effectively, the REST API makes third party integrations much easier…It even opens up new opportunities, for example to create your own WordPress-based mobile apps, or explore new and unique ways to communicate with WordPress.
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
You should now understand the overall purpose and direction of the WordPress REST API. As such, let’s get into a few specifics about how it works. 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 particular type of requests, 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.
Along with these commands, the client will send one or more lines that communicate exactly which resource is desired and what should be done with it. For example, a request to upload a PHP file into a particular folder on a server might look like this:
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 basic elements form the basis for how the WordPress REST API works.
How to start using the WordPress REST API
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 WordPress REST API, 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 WordPress 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, also check out this list of the top 10 plugins for WordPress developers. They 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, however, 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!
One more approach at using the WordPress REST API
The WordPress 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.
