34SP.com Blog

WordPress as App Engine: Using the WP-JSON API

In 2013, preparing the Google Summer of Code, Ryan McCue announced he was building a formal JSON API to be included in WordPress core. This plugin would give WordPress a REST based API to content which could be accessed by third party sources. Two years later, the plugin is well on its way to inclusion, and can now be downloaded from the WordPress repository for installation on your WP site. This level of functionality will open up new windows of opportunity for WordPress developers, since it allows WordPress to essentially run as a stand alone data service. By bundling content into easy to consume JSON packages, any WordPress site can now become the back end for a multitude of app concepts.

The API returns data from the following WordPress concepts:

The last one is the most important; since custom post types can be created for basically anything, any app concept that uses the idea of listing information (like movie times, product reviews, etc.) can use this API as its back end.

Interacting with the API is very simple; simply send a GET request at the desired endpoint:

…and the system returns a well formatted JSON package with the data in question:

This example, taken from developer Rachel Baker’s website, shows the content of one of the posts being returned.

Because there’s no front end display being generated, the response time on the API calls is very fast, and the server overhead low, meaning that even lower end WordPress installs will be able to scale this sort of functionality much larger than the traditional browser display. And, because the data is being parsed by wp-query, all of the standard query args can be applied to the output. For example, to filter by category, you simply add the filter call, and specify the category in question:

To return your custom post types, send a type arg with the query:

Adding, updating, and deleting all of the supported data objects is supported via the PUT request, which requires authentication:

Authentication is achieved by installing the separate Basic Auth plugin, and passing a request to the /oauth1/authorize endpoint, which creates an access token for the requesting application. There are a number of scopes for authorization spelled out in the documentation.

There are some weaknesses to the default functionality, not the least of which is native support for displaying custom fields. Fortunately, there are hooks in place to allow you to shape that output. For example, if you use Advanced Custom Fields, and want to return those fields with your call, the json_prepare_post hook can be used to pregather the fields you’ve created, and send them along as an additional key/value pair in your JSON return:

While the possibilities are exciting, it’s not quite ready for prime time just yet. Despite having a stable version in the WordPress plugin repository, development notes on version 2 indicate there will be no backwards compatibility to version 1, and there have been two recent security patches released closing some pretty substantial holes in the API. Additionally, although initially slotted for inclusion with 4.1, it didn’t make that goal, and doesn’t appear to be on the change list for versions 4.3 or 4.4. Anyone working with the development version at Github is met with the following message:

The “develop” branch is undergoing substantial changes and is NOT COMPLETE OR STABLE.Read the in-progress documentation to introduce yourself to endpoints, internal patterns, and implementation details.

That being said, it’s absolutely worthwhile downloading and experimenting with the plugin now, as this represents the next generation of WordPress development. Those familiar with the architecture will have a leg up when it is bundled into core, likely early next year. Once it’s integrated, you can expect to quickly see a bevy of new WordPress admin apps to make it easier to do things like post photos from your phone to your site, but for those creative enough to see WordPress as the object engine it is, this will usher in an era of WordPress powered apps.

How would you use the API? Let us know in the comments below!