WordPress started off as a humble blogging platform, and somehow found itself becoming a fully-fledged content management system that powers a significant proportion of the Internet, including this very website. Despite that, WordPress has a number of notable limitations, including a proper API.
Well, that’s not quite true. Of course, for many years WordPress has had an XML-based Application Programming Interface (API) that allowed developers to create third party applications that interact with WordPress. But XML is horrible. It’s slow to parse. It’s hard to read. It’s astonishingly verbose. JSON is much, much better. It’s quick to parse, more human-friendly and has rapidly became the language of choice for API developers.
For a while now, developers have been crying out for a JSON API for WordPress. This would make it drastically simpler to create third-party applications and websites that interact with WordPress-based websites in a way that is modern, and supported across a wide variety of languages and platforms.
After almost eleven years of waiting, their prayers have been answered. The (snappily named) JSON REST API plugin has been in the works for a while now, and has finally reached version 1.0. This means that it’s reached a feature completeness, and has a level of stability that makes it ready for production environments. What’s more, the functionality of this Plugin will soon be integrated with WordPress core, with it expected to be introduced fully by WordPress 4.0. It really is the future.
This is a milestone release of a major plugin, and one with significant promise for developers, site owners and consumers alike. Convinced? Here’s how you can start using it today.
Installing The Plugin
There are a plethora of plugins that promise to make it easy to add a JSON API to WordPress. However, none of them are as polished and complete as the official, genuine article.
When you head into the Plugin browser in WordPress, make sure you download the one that says ‘JSON REST API (WP API)’ and is by Ryan McCue, who is a member of the WordPress core team. This article only address that specific plugin.
Interacting With The API
Once installed, the WordPress JSON API will be exposed under the http://yourdomain.com/wp-json/ directory. Any queries to the API must be sent here, and can made by sending a simple HTTP request through your web browser, or through a HTTP library in your favorite programming language. The next few demonstrations of the API will be pretty much focused upon the usage of the API. We’re going to be querying it through the web browser, although in the real world you’ll probably end up using something like Python’s venerable Requests library, or CURL.
Simple enough. But we’ve still not discussed how to query the API. As I’m sure you guessed, the WordPress API is phenomenally huge. I mean, WordPress is huge. It’s a project of gargantuan size, consisting of millions of lines of code and thousands of contributors. There’s no way we can cover the API in its entirety in a single blog post. If you’re interested in reading further to this API, you’d be best having a look at the documentation, which is simultaneously comprehensive, yet also surprisingly easy to read.
So, let’s start. First, let’s see the various types of queries we can make against the JSON API. Open your browser and navigate to http://yourdomain/wp-json/.
As you can see, this comprehensively shows the actions you can make against the JSON API, and includes adding and manipulating user data, adding posts and viewing posts that have already been posted. Handily, this shows which requests require variables being passed, as well as the HTTP methods that can be used against them.
But let’s move on. Here you can see we’ve navigated to a view showing all posts that have been published. Not only do you get the posts themselves, but a significant amount of metadata for each post.
If you want to select an individual post, you you just need to add a forward-slash and the numerical ID of the post.
You can also compose search queries through the API, allowing you to bring back posts that match a specific query. This is done by sending a HTTP request to http://yourdomain.com/wp-json/posts?filter[s]=query.
You can also access and update user information through the API. Although, it’s worth noting you need to be authenticated. This is reassuring, as an API can often be an avenue to information disclosure and security breaches.
So, why does this matter?
Firstly, it means that it’s never been easier for developers to integrate their applications with the WordPress platform. Expect to see some highly impressive mobile applications and websites springing up around the WordPress platform. Also, expect WordPress clients to find their ways to niche mobile computing platforms, such as Blackberry 10 and Firefox OS.
We can also unlock the data retained within our WordPress sites without having to manually perform database queries, use the much (and justifiably) maligned XML-RPC based API, or writing complicated web-scraper programs using a platform like Scraperwiki.
Furthermore, it suggests that WordPress is moving away from being a platform used exclusively for blogging and content management, and has a vision of becoming a tool for creating more complex and ambitious products, as indicated by the inclusion of an extensible, JSON API that will eventually find its way to WordPress core. One might think that it’s gunning for Django.
Are You Excited?
But what do you think? Are you a developer? Excited about being able to access WordPress with a JSON API, or think it’s a waste of time? Are you a consumer and excited about seeing WordPress integrating with more products and services? Let me know your thoughts in the comments below.