WordPress is without doubt the most used CMS system around. Various sources peg the usage around 20-30% of all web sites. Whatever the correct figure, there is no doubt that the collective content of WordPress sites is enormously large. However almost all content is virtually held in independent WordPress sites with no way to easily access a sites content programmatically. Of course we have RSS feeds, but it is severely restricted and has a totally different purpose.
I’d always felt a need for WordPress to have some kind of way to share the content of blog posts and other data with the world. A while back I had written an article for Smashing Magazine on the topic of sharing WordPress content, although in a limited context.
WordPress and REST API at a glance
As WordPress is moving towards becoming a fully-fledged application framework, we need new APIs. At present a REST api plugin is available to access your site’s data in simple JSON format, including users, posts, taxonomies and more. Retrieving or updating data is as simple as sending a HTTP request. Once the REST API plugin is installed other people can access your sites data programmatically, opening up a wide range of integration possibilities.
For example you could create a SaaS web application that analyses other people’s blog posts and taxonomy data for SEO purposes. Without the API one has to parse the post first before analysing it further. We could also create mobile, desktop or web applications that can manipulate your WordPress site through the REST api – like creating, editing, deleting posts; checking comment status etc.
Another major advantage is that now you can integrate WordPress with other frameworks and languages. For example you can now create Rails applications and access some WordPress data using the api; or you could use a single WordPress back-end and create multiple front-end UI’s for different devices and access the same content everywhere.
Installing the REST API plugin
Just grab the plugin from here, install it as usual and you have a REST api at your disposal. Now retrieving or updating data is as simple as sending a HTTP request. The REST endpoint is ‘/wp-json’. For example sending a GET request to my site url when the plugin is installed is the following, which will return a JSON response that list the metadata for the various calls available :
You can use curl to test the api endpoint.
C:\localhost\A>curl -X GET http://www.codediesel.com/wp-json
My favorite tool however to test remote apis is ‘Postman’, a excellent chrome extension. It allows you to compose various HTTP verbs along with the headers and retrieve the response in various formats. However, for this post examples we will stick with curl.
To get content for a particular post along with the various meta data for the same, you can issue the following, here the number ‘3476’ is the post number.
C:\localhost\A>curl -X GET http://www.codediesel.com/wp-json/posts/3476
Authentication of requests
It would be a security nightmare if people accessed and changed blog content willy-nilly using the api. Obviously api requests that change the sites content – like creating new posts, editing posts, creating users etc. requires authentication. Currently OAuth authentication is the main authentication handler used for external clients. Basic Authentication is an optional authentication handler for external clients. Due to the complexity of OAuth authentication, Basic authentication can be useful during development. However, Basic authentication requires passing your username and password on every request, as well as giving your credentials to clients, so it is heavily discouraged for production use.
Note that to use Basic Authentication you need to install the Basic-Auth plugin.
A sample curl session to create a new post using Basic Authentication is given below.
C:\localhost\A>curl --user admin:password --data "title=hello world 3&content_raw=test3" http://www.codediesel.com/wp-json/posts
This has been a overview of the WordPress REST api and a quick glance on how to acccess the same. More details of the api can be found at the official site, wp-api.org.