Ryan McCue on Creating The JSON REST API for WordPress

In the not too distant future, the WordPress core is going to incorporate a powerful new API that will open new doors for the platform to be part of the interactive web. Long time WordPress hacker, Ryan McCue is busily creating a JSON REST API that will pave the way for outside applications to be able to communicate more easily with WordPress.

A Quick Introduction to Ryan and JSON

Ryan first got involved contributing to the WordPress core about 6 years ago. Back in the day you could find him helping out in the #wordpress IRC channel and answering questions. This eventually led him to start making patches to core for issues. He’s now creating a JSON REST API for WordPress as part of his Google Summer of Code project.

Ryan the WordPress hackstar
Ryan the WordPress hackstar

You might be wondering, as I was, what in the world is a JSON REST API? As I’m not an engineer, I did not have the foggiest grasp of what this API can used for before chatting with Ryan over email. I asked him to school us in the basics and he obliged:

JSON is a data format based on Javascript’s representation of objects, but it’s widely used because it can be easily represented in almost every programming language.

The project uses JSON as a format since basically every language can understand it, and it’s extremely easy to work with. The project additionally uses REST semantics, which is a way of building applications that make full use of the web and existing tools. The benefit of both of these is that any program which can access the web can use the API, leaving developers only the WordPress-specific code to write.

For comparison: the current mobile apps use the XML-RPC API, and up to 40% of their code is just to understand the XML properly, whereas JSON support is built-in to iOS and Android natively.

The JSON REST API Will Affect Everyone Who Works With WordPress

I asked Ryan how the JSON REST API will affect WordPress users and developers. It seems that while the API is not readily visible to users, they will experience the benefits of more interactive WordPress websites. Developers will also have an easier time creating this experience. He believes that it will impact everyone:

The JSON REST API is a simple but powerful way to interact with WordPress. Mobile, desktop and web applications can get data from WordPress and do anything you can do via the admin panel. It’s like the admin panel, minus the UI.

This project will affect everyone who works with WordPress. Mobile and desktop applications can move past restrictions on WordPress’ existing APIs and start working with WordPress in much deeper ways, while themes and plugins can become much more interactive. The availability of this as a core feature also means less time spent by developers creating something similar, and more time spent creating actual features.

In simple terms, for developers, this is going to be like upgrading all the old tools in your garage to be power tools, so you can focus on building. McCue calls it a whole new generation of tools:

As Matt noted in the recent State of the Word, WordPress is beginning to transition to a point where we’re building not just sites, but applications. Themes have taken us this far, but we’re moving to a web with much more user interactivity and we need a new generation of tools in WordPress to support these uses.

Practically speaking, what will the JSON REST API be used for?

I asked Ryan how he anticipates that developers will use the new API. He related a few practical use cases:

* The upcoming O2 theme by Automattic (intended as a replacement for P2) includes a similar API to power the live reloading, commenting, infinite scroll, frontend posting and other features. Once this plugin is in core, the O2 developers will be able to replace their custom code with this API (which I hear is a significant portion of their codebase)

* Mobile apps will be able to replace the clumsy XML-RPC-powered APIs with a much smaller set of tools for dealing with this API, enabling them to spend more time working on cool features and less time fixing issues

My eventual hope is that a lot of the customised admin-related Javascript and backend code can be replaced with API-powered code, but that’s a pretty long-term goal.

Overall this is going to be a giant step forward for developers who are having to try to create a similar API from scratch in an attempt to build interactive features.

JSON REST API Proposed for WordPress 3.8

McCue has proposed the API for 3.8, but the GSoC restrictions require that 100% of the code has to be written by him. These restrictions do not lend the project much collaboration at this point. Very soon the Summer of Code will conclude and McCue plans to form a team to work on the plugin and get it ready for
integration.

Although it may not be ready for WordPress 3.8 due to time constraints, McCue hopes to see it in the core in some form in one of the next few major releases. He’s very eager to get new contributors involved and would appreciate any feedback on the project.

Before talking with Ryan I was clueless about the importance of the project he’s working on but now I’m excited about the possibilities that the JSON REST API will open up for WordPress developers. Ryan’s work is currently housed within a plugin. If you’d like to test it and check it out, you can download it from github or wordpress.org. If you need help getting started, check out the docs Ryan has created or get in touch with him on Twitter.

23 Comments


  1. This is fantastic. Having heavily extended the current WordPress XML-RPC API for Spokal’s WordPress integration, I can confirm that it is pretty archaic. Looking forward to having a modern API to work with!

    Report


    1. Looks like this plugin here about is copy of another plugin…. Why don’t you give credit to original author and call this fork.

      Report


  2. @Sarah Gooding -Aha thanks. Trying to figure out which to use. The plugin is extendable with modules to setup any JSON REST call you could imagine.

    I wonder how the flexibility of the new implementation will look.

    Report


  3. Really excited about this. Props to Ryan for taking this huge steps. There are hell loads of things I can do with. Now we can make use of Backbone.js to create single page application or to keep things faster.

    All the best Ryan :)

    Report


  4. Together with a new widgets interface, this is one of the features I’m most excited about coming to core! Hope the Pods project will extend this to work with pods data as well. Using WordPress as a self-hosted backend for any kind of app will become very interesting.

    Report


  5. Does anyone know if there will be a token based system with the new API? Avoiding the need for sending user login details over the wire would be darned handy.

    Report


  6. Very exciting news for many reasons but just this together with Backbone.js is going to be HUGE for WordPress. Well done Ryan for all your hard work on this!

    Does this mean we will be seeing a WordPress app store anytime soon? ;)

    Report


  7. @Ryan Hellyer -There isn’t a built-in token-handling method, as that’s firmly plugin territory. However, the authentication system is (of course) pluggable (in fact, it uses WP’s normal authentication, but with an additional handler for HTTP Basic authentication). I happen to have a plugin that does OAuth 1.1, so I might end up releasing a plugin to do this. :)

    @David Gwyer – I happen to be working on a project for just that. ;)

    Thanks to everyone for the kind words, and to Sarah for the interview!

    Report


  8. @Ryan McCue -You said “that’s firmly plugin territory”. Why is that so? I assumed that a token system would be kinda generic and tie in well with the API itself. The official WordPress mobile apps. in particular could make use of it.

    Report


  9. @Ryan Hellyer – If we implement a token system, the question then becomes, how do we handle this? We could create our own system, but it seems like a waste to reinvent the wheel, so we’d probably go with an existing system, such as OAuth. I know from experience that OAuth is not exactly trivial to implement (althought OAuth 2 is better), so it would be a fairly heavyweight feature to include in core.

    Not saying it won’t happen, but I suspect it’ll stay in plugin territory for now. That might be reconsidered based on what we as a team decide though.

    Report


  10. @Ryan McCue -Yeah, it’d need to be oAuth I think. I think it is a worthy goal to pursue, simply so that the official WordPress apps. can connect back to base in a secure fashion.

    Report


  11. So, besides the previous plugin already mentioned (json-api), there’s also another plugin also called wp-api (I’m assuming not the same one, as it’s already at version 1.0.3).

    Anybody done any work with either of these existing plugins?

    Report




  12. Guys this looks like a big improvement. But it’s like all the other Json Apis it’s not really restful.

    When is someone going to do it properly? A user should be able to just use the same urls as to get html, xml, or json versions of all content (based on content negotiation) and if desired also post updates to the same urls.

    That would unlock the true power of rest and wordpress.

    Report


  13. @Pete – HTML/XML/JSON is not really part of being RESTful, however it’s theoretically possible to do this already. The API only translates to/from JSON in a select few places, so you can serialise it to XML, ZeroMQ, MessagePack or whatever you want, intentionally.

    (It’s also RESTful, since you send updates to the same URL itself, but only for the API itself. It’s intentionally self-contained at the moment, but that might change in the future.)

    Report


  14. @Pete – How do you feel about removing the permalink options from WordPress then? Personally, I’ve never seen a REST API who’s endpoints change depending on a customizable frontend appearance option that has nothing to do with the API.

    Permalinks are the reason WordPress can’t do that for it’s REST API, and those obviously aren’t going to disappear anytime soon, so the REST API has no choice other than to expose it’s own new endpoints.

    Report


    1. Bryan,

      This is not a major problem, most sites don’t change their permalink structure (mainly for seo reasons). The benefits in terms of usability, semantics, documentation etc are huge if a truly restful approach was used.

      This API is good but its needs to be truly restful.

      Report


Comments are closed.