Public WordPress RESTful API using ThermalAPI plugin

REST is an architectural style in which methods (verbs), uniform resource identifiers (URIs) and other HTTP headers are used as part of a request to server. This is done in order to ask for and describe needed data/resources. RESTful API is a web service that listens for user requests. Once it gets one it sends a response containing user requested data as well as some headers that may describe the response a little bit better. Servers (services) response can be presented in many forms including XML and JSON. In this case we’ll use the most popular one, JSON. The main advantage of this architecture is that the server response can easily be cached on the client side and all of the frontend stuff is done on the client’s side. This results in a much smaller bandwidth and much richer user experience.

Why should you bother with RESTful API?

Let’s say you have created an awesome blog for your client who’s really pleased with your work. Not too much time has passed and the client realizes that there are a bunch of sites out there that have a dedicated Android/iOS app and he wants the same and, of course, he doesn’t want to write posts for every app separately. That’s one of many use cases where RESTful API WordPress integration comes in handy.

It’s not (just) about the mobile apps.

Having RESTful API on your WordPress site doesn’t need to come in handy only when you need to develop a mobile application for your client. Having a RESTful API set up, you can create richer and more beautiful web sites and applications as well. In this post we’ll do just that and we’ll do it using the ThermalAPI plugin and Backbone.js. When installed, the ThermalAPI plugin “sets up” a couple of routes on your WordPress site. Routes are used to map HTTP request URI to controllers. You can use those routes to retrieve posts, comments, categories and a bunch of other stuff from your WordPress site and, eventually display them to the application/site visitor.

Installation

Installing ThermalAPI plugin is just as easy as installing any other WordPress plugin which means that you can do it from the WordPress administration or you can download it as a zip from here. Once installed and activated you should be able to access the http://api.mysite.com/wp_api/v1/posts URL. If you see some data appear that means that you’re good to go!

Backbone Application

Next we need to setup a new Backbone.js application that will access newly created API and present the content to the application visitors/users. We will run the application on a separate host in order to distinct the application from the API. Lets name that host http://mysite.com. Now we need to download the Backbone.js from the http://backbonejs.org/ site. Once downloaded we’ll set up application structure like this:

app/
 - css/
 -- (css files)
 - img/
 -- (image files)
 - js/
 -- collections/
 ---- posts.js
 -- models/
 ---- post.js
 -- views/
 ---- posts.js
 ---- single.js
 -- app.js
 -- router.js
 vendor/
 -- (vendor stuff)

First let’s configure our router. Inside of it we’ll define application routes and we’ll map them to a handler that will handle the request of that route. So let’s create 3 routes that our application will use.

Once we have the router set up we need create handlers for specified routes. We will define our handlers inside the app.js file.

Now “route:index” handler will handle post listing and “route:single” will handle the single post display. In order to implement those handlers entirely we’ll need to “connect” our application with the API. Let’s say that every post published on a site is a entity and we describe the entity using a model. That means that we need to create our model which will describe the post received from the API. In order to create the model we’ll create post.js file inside the models/ folder and add some data to it.

Now we have added some default data that will be used if the API doesn’t return any of those defined fields. Also we’ve added the urlRoot key to our model which defines the path for the resources on the API from which we’ll collect the data. Since we have to deal with collection of posts as well we’ll need to create the posts.js collection in the collections/ folder.

Inside the post collection we’ve defined the URL from which the collection will be collected. Also we’ve defined the model which will be used in the collection.

Now, if we take a look at the api.mysite.com/wp_api/v1/posts once again we’ll see that all collection items are located inside a root element (key) called “posts”. Since this root element will confuse the collection builder we need to show the posts are located in that key. To do that we need to edit our collections/posts.js file and define parse function.

Our parse function now takes the response as a argument and extracts the posts from the “posts” key and builds the final collection out of it. Now we can implement our route handlers even more.

As you can see both of our handlers receive one argument. The first handler receives the page which will be used for pagination purposes and the second one receives the ID of the post that we want to see as a single post.

The first method checks if the page has been defined and uses that page to get data. If the page is not set (undefined) we set it to 1. Now we create a new collection instance and fetch the data. Before fetching we set the needed page as a part of the request along with the post type we want to get (post). The same thing applies to the second handler except the second handler uses the model instead of collections since we’re dealing with a single post instead of collection. We can see that both success handlers are empty and that’s because we need to create a view that will be used for data rendering. So let’s create our views.

We’ll need two views. One view will be used for the post collection rendering and the second one will be used for single post rendering. The first one will be called posts.js and the second one called single.js. We’ll store those inside the views/ folder and implement them.

views/post.js

views/single.js

In order to implement our views we have defined a few items that Backbone.js needs to create a template and also we have set up a few methods that we’ll use as helpers.

Once created we can implement the views inside the success handlers (app.js).

The only thing that’s left is to implement the index.html file in which we’ll define html for all views, create a basic layout for our application and import all JavaScript files that our application will use.

And that’s about it. We now have a fully functional application that uses the RESTful API powered by ThermalAPI WordPress plugin.

Demo

You can find the the application here: http://dev2.slicejack.com/restful-api-demo/