Anyone paying attention to Matt Mullenweg’s public appearances over the past twelve months will have noticed the steady beating of one particular drum: The importance of the WordPress JSON REST API to the future of the platform.
Matt isn’t alone in his enthusiasm. Commentators such as Brian Krogsgard have hailed it as potentially “the most exciting project for the platform since custom post types were introduced.”
In this article we’ll cover what the WordPress JSON REST API is, when it’s coming, and what you need to know to take full advantage of the truly revolutionary possibilities it’s going to open up to everyone in the WordPress world.
As a bonus, we’ll also hear the thoughts of Automattician Jack Lennox, who recently spoke at WordCamp London about building themes with the WordPress REST API, about where he thinks the API might lead the community.
But before all that, let’s get started with some general background on REST APIs.
Getting Familiar with the Concept of REST APIs
I’d like to make one thing clear right from the outset: Though I consider myself an experienced WordPress practitioner in most respects, I’m no developer.
With that in mind, my interpretation of some of the key concepts below will not necessarily be as complete in terms of technical detail as you might find if you were, for example, piling through IBM documentation on the subject. Which might be a good thing!
With that caveat out of the way, let’s review the basics.
What Is an API?
API is short for Application Program Interface. In layman’s terms, it’s the agreed set of standardized ways that a particular piece of software can be used; the rules defined for its interaction with the wider world, which govern how other pieces of software can talk to a program and how it will respond.
What is a REST API?
A REST API, in turn, is a particular architectural approach to putting together these rules. REST stands for Representational State Transfer. It’s a methodology designed to let programs talk to each other in as simple a way as possible.
It’s an inherently flexible format, but implementations are expected to share certain core characteristics. The four listed here are taken from the excellent IBM intro mentioned above:
- Use HTTP methods explicitly: It takes place over the web with standard HTTP methods such as PUT, GET, POST and DELETE.
- Be stateless: The client will include any state information needed in the request to the server and vice versa.
- Expose directory structure-like URIs: You’ll be looking at familiar URL structures like http://myexampleschool.com/teachers/john
- Transfer XML, Javascript Object Notation (JSON) or both: There is an agreed set of options for data exchange.
There’s an excellent further general introduction to the concept of REST APIs over at Tutsplus.com if you’re looking to explore more of the technical details. Alternatively, take a few minutes to go through the overview from Todd Fredrich below.
What all of the above boils down to in the context of WordPress and the REST API plugin is very succinctly summarized on the homepage of the plugin itself:
This plugin provides an easy to use REST API, available via HTTP. Grab your site’s data in simple JSON format, including users, posts, taxonomies and more. Retrieving or updating data is as simple as sending a HTTP request.
After you’ve installed the plugin, accessing your site’s data via REST is straightforward. The plugin’s homepage goes on to list some useful illustrative examples:
Want to get your site's posts? Simply send a GET request to/wp-json/posts. Update user with ID 4? Send a POST request to/wp-json/users/4. Get all posts with the search term "awesome"?GET /wp-json/posts?filter[s]=awesome.It's that easy.
As we can see there, any data returned will be in the form of JSON which leads us nicely on to our next section.
Where Does JSON Fit into the Picture?
The WordPress REST API uses Javascript Object Notation (JSON) as its data format of choice.
JSON is a modern, human-friendly, data format with encoders and decoders available in every major programming language. The choice of JSON makes it easy for WordPress and any third-party application to send information back and forward to each other in a mutually intelligible format.
For those entirely new to JSON, you can find a good introductory overview at Copter Labs.
The key thing to understand when thinking about REST APIs is that everything is taking place over the web via HTTP – data in and data out.
There is a true separation between client and server in place, and no need to be inside either the WordPress front-end or admin panel for any requests to be read or executed.
It’s exactly this seemingly small distinction that opens up a truly exciting world of further possibilities.
Before we get into them, let’s quickly review the current state of the actual WordPress JSON REST API plugin itself.
The WordPress JSON REST API Plugin
The WordPress REST API is currently under active development as a feature plugin. As experienced WordPress users will know, the journey from feature plugin to core is not always a smooth one. When you’re dealing with a feature of the size and complexity of the WordPress REST API, that’s even more the case.
The REST API was originally scheduled for integration into core in version 4.1 and is currently – optimistically some might say – pencilled in for WordPress 4.3 around mid-August, 2015.
An excellent, recent overview from Josh Pollock over at Torquemag.io gave some great insights into a number of behind-the-scenes reasons that are making that August date look increasingly unlikely.
Chief among them is a recent decision to draw a hard line between the existing Version 1.2 of the plugin and a scheduled Version 2 designed specifically for core inclusion.
The feeling now seems to be that “sometime in 2015” is the best we can hope for, but don’t be surprised to see that date slip.
Of course, this doesn’t mean that developers aren’t free to start experimenting straightaway – version 1.2 is fully ready to be used and tested as a plugin. Just be advised that the full core implementation may be some way away.
Full documentation for the current version is available on its own dedicated site at wp-api.org, which includes Quick Setup instructions and getting started guides for developers looking to kick the tires.
Three further useful pages to bookmark to stay on top of developments are the following:
- The WP REST API Plugin homepage
- The WP REST API section on Make WordPress Core
- The WP-API Github repository
Make no mistake about it – despite whatever short-term stumbling blocks the plugin may have hit, this functionality is coming to core. And it’s going to be huge.
Let’s start drilling into reasons why that’s definitely the case.
Why the WordPress REST API Matters
At this stage of proceedings, I can picture two quite specific responses to what we’ve covered so far:
- What does this all this mean for me? Isn’t this just some “technical tidying up behind the scenes” type of project?
- Oh my goodness, this changes absolutely everything!
Allow me to explain why I think the latter is very much more the case than the former.
To put it in a nutshell, the integration of the JSON REST API will mark the final transformation of WordPress from its humble roots as a blogging solution into a fully-featured application platform.
By providing an agreed, standardized programmatic interface between WordPress and the outside world, the software opens itself up to every other application and development environment on earth.
This is absolutely huge news. Here are five solid reasons why:
1. Cutting the Cord with PHP
Despite some of the flak it has attracted in the past, PHP is still the powerhouse behind over 80% of modern websites, and is actively endorsed by web giants such as Facebook, and of course WordPress itself.
The last decade, however, has seen enormous advances in other languages such as Ruby, Python and Go, in terms of speed, tooling and available frameworks.
The REST API gives those languages instant access to the full range of WordPress’ native functionality. This reason alone should be enough to get any developer or site owner’s mind racing.
A good way of instantly grasping the potential on offer here is to consider the world of plugins. Any WordPress plugin you can think of is now a candidate for first-class integration into other frameworks, such as Ruby on Rails or Django.
When you think of the richness of the WordPress ecosystem and how successfully aspects of it (such as theme frameworks and plugins) have been monetized, the potential to port to brand new platforms is a mouth-watering one in terms of possible revenue for developers.
2. True Mobile Integration
WordPress has arguably done better than most mainstream content management systems in meeting the challenge of displaying websites across an enormous range of devices (through responsive theming). However, true integration with the respective worlds of iOS and Android outside the browser has remained an elusive goal.
There are native WordPress apps for using the application itself on both Android and iOS of course, but true third-party integration is far from common.
Using the REST API, mobile developers will potentially be able to treat WordPress installs as just another server, with defined endpoints from the point of view of their apps. That fact alone opens up WordPress as a possible true backend for native mobile apps and paves the way for all manner of future integrations.
AppPresser have a great run through of the basics of how this can work over at their site to spark your imagination further.
It’s worth noting here that app usage on mobile remains around the 80% level, so it’s clear that WordPress is going to have to move towards the app environment rather than the other way around. The REST API is the way this will happen.
When you consider the amount of websites out there currently on WordPress that are also running entirely separate app versions of aspects of their online offerings, the scope for future integration here is truly immense.
3. The Front-End Will Be Strictly Optional
The previous two points introduce a wider third: Use of the front-end of WordPress will become strictly optional.
From the point of view of the API, the WordPress front-end is merely another external application hitting its endpoints. The implications of this are huge.
WordPress is now just another item that can be seamlessly added to any modern developer’s toolbox without having to step through its templating system, log in or deal with the nuts and bolts of WordPress internals.
Expect to see a revolution in theming and plugin use cases as the implications of this sink in for developers and site owners worldwide.
4. The WordPress Backend is Ready to Be Reimagined
For as long as the WordPress admin has existed, somebody, somewhere has found something to complain about it. And I’m the first to admit I’ve been guilty of that myself on occasion.
The potential full integration of the REST API in core opens up the possibility of the WordPress admin itself being truly reimagined, to the point where developers will be finally free to define their own entirely separate take on it rather than just customizing corners of it here and there.
Examples of this are already creeping into the wild – with WordPress.com’s unique take on the admin panel being the highest profile example to date – though admittedly that is powered by the separate WordPress.com API.
Recent articles from Jeff Chandler over at WP Tavern and Noel Tock offer interesting overviews of both the current landscape and some of the directions the WordPress admin could go in the future – including references to current experimentation by HappyTables and Pickle in this regard.
5. Getting on Board the Javascript Bandwagon
At this stage it is more or less official: Javascript is eating the world.
We mentioned the rise of frameworks such as Rails and Django in the first point above, but the real shooting star in terms of languages in the last five years has undoubtedly been Javascript.
The emergence of Node.js on the server-side, combined with a new breed of front-end frameworks such as Angular JS, Backbone, Ember and React, have put Javascript firmly front and center.
The REST API makes WordPress a potential partner with these technologies, rather than a competitor. When you consider the heavyweight backing Angular JS and React in particular have – Google and Facebook respectively – this is a smart position to take.
From the point of view of developers and theme designers, it means they are free to explore the best in breed of the new technologies in tandem with honing their existing WordPress skills – truly the best of both worlds.
Practical REST API Projects
It’s still early days in the world of the REST API, and we’ve barely scratched the surface in terms of what lies ahead with the points above. Before we finish up though, I’d like to introduce you to two recent deep dives into the specifics of what the API can do.
The first leans more in the direction of theme development options, while the second is more concerned with application development.
1. Jack Lenox’s March 2015 London WordCamp REST API Theme Presentation
This is the talk I was lucky enough to find myself at recently, and that actually served as the spur for this entire article.
Jack does an incredible job with stepping through the basics of the API and provides concrete theming examples throughout. So, rather than trying to paraphrase his talk, I suggest simply watching it in its entirety.
Two major points leapt out for me while watching:
- Developers from major web properties in the UK such as The Sunday Times are already looking to leverage this technology, reinforcing early reports of large media sites in the US such as the New York Times also taking it for a spin. This type of early adoption, however small or experimental, tells me that there is a significant number of high-calibre developers out there just itching to give this a shot in production.
- The intersection between existing Javascript frameworks – such as Angular JS, React and the REST API – is going to present both a huge opportunity and a challenge for theme developers.
A Brief Q&A With Automattician Jack Lennox
Jack took some time out of his work at Automattic to get back to me on a few questions I posed via email after I’d had a chance to process his talk at WordCamp London.
I hope the interview will give you some food for thought about where the REST API might take WordPress. Thanks Jack!
Q: What was the biggest challenge you faced personally as a developer getting to grips with the REST API?
A: With theming, I think the hardest thing to get used to is working out how to recreate all the things that you take for granted when doing things the conventional way. For example, routing; in a normal WordPress environment, routing is not something that you have to think about. There are lots of other challenges related to how the REST API has been developing. For example, showing widgets, dealing with things like the body_class changing as you move from page to post to page, etc.
Q. What aspects of the REST API are you most excited about using in future projects?
A: Batch requests. These are still in development but will allow you to make requests of multiple different endpoints from the REST API in one HTTP request.
Q. What’s the best general resource/resources you’d recommend to non-developers/designers looking to explore working with the REST API?
A: I think the most useful resources on working with the REST API are based in the JS world. Backbone, for example, is a framework designed for working with REST APIs.
Learning Backbone helped me understand what you can do with a REST API. Addy Osmani’s TodoMVC samples are incredibly useful for understanding the basics of all of the emerging JS frameworks and libraries, in particular the Backbone one.
Q: As it opens up to the wider web and other programming languages via the REST API, where do you see WordPress heading as a platform rather than a CMS in the next five years?
I think we have been seeing WordPress in unexpected places for quite some time now, but I think the REST API will lead to WordPress being used in ever more diverse environments.
That said, I think the WordPress that we know and love today will still be very much present in one shape or another in five years’ time. Look at how many people still use Blogger.
There will be a demand for something that works well out of the box, but maybe we will see more folks creating interesting advanced implementations of WordPress that cater to specific niches in the way that HappyTables does.
Q: Lastly, a more general question, what’s your favorite part of being an Automattician?
A: Ah, there are many good things about working at Automattic. Professionally, my favourite part of working here is the enormous wealth of knowledge that is available to me from my colleagues. We have some seriously smart people at this company and I have learnt such a huge amount since I joined a year and a half ago.
But probably my favourite part of being an Automattician in terms of lifestyle is the freedom that our way of working provides. Because the company is distributed across the globe, we are timezone-agnostic. This means that Automatticians can work when they want, rather than follow any arbitrary timeframes for working.
I live in a very beautiful part of England, but it also rains a lot, so when we do get some good weather, I don’t want to be stuck inside working like most people, and I don’t have to be! I can get out on my mountain bike and enjoy myself.
2. K. Adam White’s Talk on Node.js Integration
WordPress in Weird Places: Content Management for Node Using REST is a fascinating account of WordPress being used as the CMS backend for a Node.js application on a green-field application for a Fortune 500 company.
My main takeaway from this was that the power and flexibility of the CMS portion of WordPress as an application was enough to make it a viable candidate here against stiff competition.
This bodes very well indeed for the future uptake of WordPress as a backend in application development via the REST API.
Conclusion
No matter what area of WordPress you consider your speciality, we hope the information above has been enough to pique your interest in the changes coming down the line. They are going to affect everybody.
The uncertainty over exactly when the JSON REST API will make it into core shouldn’t stop you from starting to explore it in its current state. It’s a question of when rather than if this going to happen, so now is as good a time as any to start exploring further and sharpening your toolset.
Let us know in the comments below if you’ve already dipped a toe in the waters and what sort of applications you can see yourself putting together with the new functionality.