The REST API (and How It Could Change WordPress Forever)

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:

  1. The WP REST API Plugin homepage
  2. The WP REST API section on Make WordPress Core
  3. 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:

  1. What does this all this mean for me? Isn’t this just some “technical tidying up behind the scenes” type of project?
  2. 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:

  1. 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.
  2. 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!

Jack Lenox
Jack Lenox is a design engineer at Automattic.

 

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.

Tom Ewer
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.

13 Responses

  • Mfs
    New Recruit

    Thanks Tom. A great overview of a great thing at a great time. Kudos.

    That said, what’s not clear to me are two things:

    1) Why does this have to be in core?
    2) Yes, it’s a more modern way to implement a product, but it’s still – correct me if I’m wrong – the same WP core. That is, the REST API isn’t a parallel “fork”, if you will, more of less line by line replacing older WP code, but simply an updated interface on the same ol’ backend.

    Note: That’s not a critique, just a question :)

    Given that WP is the every-man / every-woman champion – and dev’ing in this new world is certainly not kid’s stuff – it’s going to be interesting to see how much thunder the WP w/ the REST API can steal from more serious technical heavy weights (such as Drupal).

    Yup. One way or another, exciting things are about to happen.

    • Author

      Hey Mfs,

      1. It doesn’t have to be, but suppose I would counter with, “Why *shouldn’t* this be in core?”
      2. That’s my understanding too (although I could be wrong). Is that a bad thing?

      WordPress is the every(wo)man champion, like you say, and I think the REST API would only contribute to that. I suppose it might not make it so much the everydeveloper champion though perhaps ;-)

      Thanks for sharing!

      Tom

  • New Recruit

    I have to say after alot research around wordpress API’s I was not satisfied with anything in market. I just decided to use to loopback by strongloop a node.js /express server to expose the rest services. This gives me all the functionality you are talking about with all the benefits and scale of node. They will actually map all the tables to a rest service on fly if you want to get up and running quickly. Check it out here https://github.com/strongloop-archive/loopback-example-mysql. The main issue is really how well is your mysql instance going to scale with all the new connections and how you horizontally scale out your php files.

  • Dan
    New Recruit

    Tom, you wrote:

    “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.”

    WordPress actually does not have a templating system of any kind in core. This is completely optional already depending on themes and plugins you use.

    I can see how a single, efficient, modern API any other application can deal with is useful for big existing WordPress sites that need some type of interaction with other platforms — say WooCommerce to a Rails application, for example. I can see how it’s useful even for WordPress themes and plugins small sites and blogs might use. In the latter case you’ll be carrying a lot of legacy core code you never use, but what you’re still saddled with in both cases is a data model locked onto “posts” and “postmeta” that’s not terribly versatile. How much is that seen as a problem? Just the next big thing to tackle?

    • Author

      Hey Dan,

      I wouldn’t pretend to know, but I do agree that WordPress is built on a vast codebase that may or may not apply particularly well to future plans. But I suppose that is the beauty of open source – what started as a modest fork has become the world’s biggest CMS, and God knows where we will go with it next. I for one am very excited!

      Cheers,

      Tom

    • New Recruit

      > “WordPress actually does not have a templating system of any kind in core. This is completely optional already depending on themes and plugins you use.”

      This can be misleading. WordPress data and the way it handles templating is closely tied together. The whole point of bringing REST API is to separate data and layout.

      What Dan wrote is true.

      > “…through its templating system, log in or deal with the nuts and bolts of WordPress internals…”

      As you can imagine, your whole “app” can be built in EmberJS for example, where you could recreate WordPress back end. This will tremendously improve performance, since much of the processing is offloaded to the client, and only interaction between backend and frontend is via JSON. This is not just limited to JavaScript frameworks, but anything that can consume JSON.

      I hope WordPress moves more towards “components” model, like Drupal with Symfony2, and the likes of Laravel.

      Great discussion.

      Best

  • The Incredible Code Injector

    Nice writeup Tom.

    About a year ago I had a young dev ask me about iOS App development. I set a project for him to build an app that can save user info and allow those users to post information that others in his app can access. At the time I was thinking… “If only I could tap WordPress and make his job a little bit easier and actually give him a platform.”. A quick search revealed the WordPress REST API.

    In less than 30 minutes I had his test server up and he was using the REST API to push and pull data out of WordPress. That’s when I realised how awesome this could be. When I heard it was coming to core I was super excited!

    I’m all for it. Let the awesome be more awesome!

  • New Recruit

    Great article. We’ve done some work with the JSON REST API at our agency, but we’ve run into some critical problems. Sometimes there are server restrictions on how much data can be served, and these restrictions can show up in some strange places. Like header information. Something you don’t have to worry about with data accessed on the server side.

    The site we built was http://www.bhdstudios.com

    We also ran into some performance issues that were difficult to resolve. It’s an awesome, and necessary direction to go in, but there are a few pitfalls. As great as WordPress is, it’s starting to show it’s age, which I wrote a little about at http://blog.mwright.com/post/why-wordpress-is-so-important . I also referenced this post, which is definitely a must read for any WordPress developer.

Comments are closed.