One of the hallmark features of WordPress 4.1 — yes we just got WordPress 4.0, and you’re right, it is really awesome — is likely to be a new way to remotely publish to WordPress: the hallowed “JSON REST API.” But for a lot of people, I know that that sounds like a whole lot of random meaningless letters. So my goal is to explain the current state of remote publishing and control of WordPress sites, how the forthcoming JSON API impacts that, and what it all means.

Understanding the Basics of Remote Publishing

If you’ve never heard the term, “remote publishing” may not make a lot of sense. What people mean when they say “remote publishing” is simply that you’re publishing to a website without actually visiting that website. I might use the Mac app MarsEdit to publish this post to WPShout, rather than using the WordPress admin interface. (I didn’t, but I could.) Or I might use the WordPress iOS or Android apps to do it. Or I might use a collaborative web writing platform for publishing, because my writing team is used to it. (On the last, I don’t know that one exists today that’ll do publish to WordPress, the ill-fated Editorially did.)

The way that WordPress allows and accepts these requests today is though something called the XML-RPC API.

All of these services would be allowing me to publish to this WordPress site not by visiting the pages of the site, but instead making requests to WordPress on my behalf. The way that WordPress allows and accepts these requests today is though something called the XML-RPC API. An API can be thought of, generally, as the public face that a software system shows the world. The XML-RPC API creates the metaphorical buckets to put data, and buttons to change things that WordPress has decided it makes sense to expose to the world. (I wrote a little more about APIs in general over on the Press Up blog a few months ago.)

So when the WordPress iOS app wants to publish an article to WPShout, it takes the post content I’ve put together, arranges all the data around it — dates, tags, categories, etc — in the WordPress dictated way, and sends it off to the WordPress install. If the request has proper authorization — I am a user with valid credentials — WordPress will make a new post to match the one that the iOS app sent over. If there’s something wrong, our WordPress install will respond as such.

Understanding XML-RPC’s Usefulness and Format

As we said, for WordPress 4.0 and below (well, down to 2.7 or so…), the primary way you remotely publish or change your WordPress site was through something called XML-RPC. There are two important parts of XML-RPC: XML & RPC.

What exactly is XML?

XML is deeply nested and rich format for data. By design, almost all information in the world could be marked up in a reasonably readable form with XML.

Let’s tackle XML first. XML stands for “Exstinsible Markup Language.” Its format is close enough that if you squint you could mistake it for HTML, but XML is a very rich format. For a while, people actually wanted the future HTML to be as a dialect of XML — that was the so-called XHTML that you’ll still see references to around the WordPress world. We also mentioned XML very briefly recently in our discussion of Ajax in WordPress, because while it’s not (always or even mostly) the case that XML is the data-interchange format people use when doing Ajax, that’s where the X in the word comes from.

The details of XML format aren’t all that relevant to our discussion here, but just so you understand some of its qualities I’ll explain a bit. XML is deeply nested and rich format for data. By design, almost all information in the world could be marked up in a reasonably readable form with XML. Microsoft Office — in their newer .xlsx and .docx formats — are using XML under the hood. But by virtue of being this powerful and descriptive, XML has another quality: it’s a bit long to write and hard to parse.

The XML-RPC Standard

So we know that the data format for XML-RPC is XML, and we know what that means. The other half of the name is that RPC. In XML-RPC, the RPC stands for “remote procedure call.” XML-RPC is a common standard, or interface, that was defined way back in 1998. Essentially it specifies the format of XML that you should use to talk over HTTP. It’s not the only such definition, but what’s important for us about it is that it’s the one WordPress chose. Again the specific of the format aren’t all that interesting or useful to discuss, but they’re easy to find, you can start on the Wikipedia page.

The big thing about XML-RPC that’s useful to understand, especially in the context of the JSON REST API for WordPress, is that your core concept is actions, rather than entities.

The big thing about XML-RPC that’s useful to understand, especially in the context of the JSON REST API for WordPress, is that your core concept is actions, rather than entities. What does that mean? When you’re trying to make a new WordPress post through XML-RPC, you call a method defined by WordPress called “newPost.” And if you want to get a categories’ details, you call the “getTerm” method on the API.

What You Can Do Remotely on a WordPress Site

So we understand XML, we understand XML-RPC, what’s possible? You can, from your Android WordPress app, make a new post, edit a page, see all of your tags, etc. You can probably even tweak a few options, and maybe toggle some user permissions. All these things are possible in the API, though I can’t say with confidence what’s in the Android app today. Things that you can’t do in the app, or through the API: create or change the theme you site is running, install a new plugin — intensive stuff that’s pretty involved for WordPress to do and generally benefits a lot from user feedback.

And you can do these thing not just in tools we’ve mentioned — apps for your desktop, tablet, or phone — but also software libraries for other languages. In some recent Press Up client work, I used this PHP package from Hieu Le which was rather simple to work with. There’s a similar project for Ruby as well, and almost certainly far more in other languages than it makes sense for me to list. Basically, if a technical person wants, they can pretty easily help you to do many things on your WordPress site remotely, and they likely can even do it using XML-RPC and don’t need to start from scratch.

What the JSON REST API Means

As we’ve covered, there’s a ton of power packed into XML-RPC for remote data retrieval, publishing, and control of WordPress sites. So why all the excitement around this new JSON thing? Well, as I hope I suggested to you in the last section, there are two big differences between the two.

Why JSON is Different, and More Loved, than XML

JSON — which literally stands for “Javascript Object Notation” is very familiar to anyone who’s ever programmed Javascript.

Opinions differ a fair amount about the “betterness” of XML or JSON, but they both serve a similar purpose. Both are ways to convert data into a standardized format that is easily shared. Both are common and relatively easy to work with in most common programming language because of their longevity.

A lot of people like JSON for two reasons:

1. JSON is Javascript-native. Unlike XML, which is rather long and verbose, JSON — which literally stands for “Javascript Object Notation” is very familiar to anyone who’s ever programmed Javascript. Literally the way you write a data structure into a Javascript program is how it looks when put it into a JSON format. So it’s got familiarity going for it.
2. JSON is much more concise than XML. XML, as we said, is a very powerful syntax system. But that power means that you’re forced to write a lot more long and explicit characters than you might want. And that is not something in style today. People like JSON because it feels exactly powerful enough to meet their needs, without feeling like it’s got the “could define anything” power and overhead of XML.

So that’s why people prefer JSON to XML. But many people also prefer the other half of the name as well.

What REST Means, and How it Differs from Remote Procedure Call

I feel like we’re already running long, so a treatise about the power, intelligence, and wisdom of REST should probably be held for another time. But in summary, REST — which stands for “representation state transfer” — is the current hotness for a exposing your website’s content and functionality to other programs. Its preferred to alternatives like RPC, or SOAP (which descended from RPC), because REST is the access pattern that underlies the entire internet.

Rather than working in terms of “procedures,” REST is about state. So rather than calling a getTerm method on an API, you send a GET request — which is what your browser makes when you visit a webpage — to a terms “page” or “endpoint”, and it tells you them. If you want to add one, you send a POST request — which is what your browser sends when you send a web form — to the same endpoint. This is simpler, for most use cases, than something like RPC. It’s also, we can’t discount this factor, is what’s really popular in technology right now.

Why You Should Be Excited from the JSON REST API

We’ve covered a lot of ground. One of the primary things I hope you understand is that you can already remote publish to and get data from your WordPress blog. XML-RPC, while it’s hardly the new hotness, is still a very useful and powerful system which has served WordPress well for years, and will almost certainly continue to do so for quite some time. (Love it or hate it, WordPress doesn’t break backwards compatibility much, so we get to keep things we’ve got now.)

There are two things that make the JSON API a unique and awesome feature for WordPress’s future. The first is simply that the team working on it — the project’s GitHub presence is a great place to dive into all the great work they’re doing — is really adding a lot of great features (like much better security and authorization than XML-RPC provides) which will be a huge benefit vs. the XML-RPC we’ve had forever.

The other big benefit is that because the JSON REST API is new, built using currently-popular formats and ideas, and easier and more intuitive to use with Javascript, we’re probably going to get a huge new wave of innovation around the remote control, editing, and interacting with WordPress. Already there are a few themes that use Javascript heavily for their presentation, but with the JSON API it’ll be possible to build a single page WordPress theme in Javascript much more easily. That’s what really excites me: that the JSON REST API getting into WordPress core is almost certain to spur a lot of new interest in remote control and access to WordPress. I can’t wait to see what comes from it!

Image credit: purpcheese, monsieurlui