If you’ve spent any time in the WordPress community 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.
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.
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.
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:
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:
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:
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!
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 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.
Do you have any questions about the REST API, and what it means for WordPress? Ask us in the comments section below!
Don’t forget to join our crash course on speeding up your WordPress site. With some simple fixes, you can reduce your loading time by even 50-80%: