WordPress REST API

REST, as you may know, stands for ‘Representational State Transfer’, but if you’re anything like me you probably have to look it up every time.

There’s something disconcertingly cryptic about such phrases as Representational State Transfer, and I suspect many people would be hard-pressed to say exactly what it means. Still, WordPress’s announcement that it’s planning to move to a REST API was greeted with great enthusiasm by the cognoscenti, so it must be a Good Thing. Well, it’s not every day you can announce an innovation that can be described (if not necessarily understood) in two whole acronyms. (You don’t need me to tell you that API means Application Programming Interface, do you? Good.)

So the WP REST API will be the WordPress Representational State Transfer Application Programming Interface. What could be clearer?

Now, it’s got to mean something, so let’s ‘deconstruct’ it a bit. Doesn’t WordPress already have an Application Programming Interface? Well, yes, in a way. It’s what the Codex describes. All the functions in the WordPress core can be seen as the API as long as by ‘application’ you mean something that resides in the WordPress namespace — a plugin or an add-on, or perhaps a new template file. But if the application is an external program that wants to access WordPress features it’s another story altogether.

Try, for example, writing a cron script (no, not wp-cron — I mean an external, asynchronous script running as a cron task), that invokes WordPress core functions, and see how far you can get. It can be done, I think, but you need to include practically the whole of the WordPress infrastructure, and give it a sensible environment to work in. Not worth the hassle. I guarantee you’ll end up doing it a different way. Now suppose the application’s running on a different server…

Of course, this all makes perfectly good sense. A system that allowed all its functions to be called by all and sundry would be hacked in next to no time. But on the other hand a system that allowed none of its functions to be accessed externally would be of no use on the web. In the simplest case, you need at least to be able to call it by sending something like

GET /index.php

to a suitable URL, and of course we do, every time we visit a WordPress site or any site that’s written in PHP.

This is a call on WordPress functionality, if not explicitly on its functions. And what’s more it uses the REST protocol, which essentially consists of the ‘verbs’ HEAD, GET, PUT, POST, PATCH and DELETE, delivered over HTTP or HTTPS. But it doesn’t allow the sort of fine-grained access that we would normally associate with the idea of a programming interface.

Suppose for example we want to get all the posts on a given site containing the search term ‘awesome’ (we’ll consider why we might want to do such a thing in a moment). It would make sense to retrieve them in a nice, reasonably compact format — in JSON for example. The REST API would allow us to do this with the command

GET /wp-json/posts?filter[s]=awesome

So perhaps what we are saying is that instead of leaving it up to the the server to decide not only what information it will deliver (web pages) but also how they will be presented (in HTML), we can see some benefit in allowing a finer-grained selection of data and letting the client decide what to do with it.

One area in which this will have obvious benefit is on small devices, particularly smartphones. Until recently anything at all sophisticated on a smartphone had to be done by an ‘app’ written in a proprietary language in a proprietary operating system. This forced developers to focus on specific device types or to work with complex and cumbersome cross-compiling systems. A REST interface will allow ‘apps’ to retrieve information, including but not limited to webpages, and display them in a manner that is appropriate to the device. My guess is that such apps (that can be written in Javascript or a variety of other standard languages) will fairly soon replace web browsers on small devices.

Interesting times!