WordPress JSON API Custom Controllers
Posted on 11th July 2015 in Code, Tips.
I recently had to use the JSON API plugin for WordPress, this has a great set of core functions for retrieving or modifying data such as posts from your database, in the form of JSON requests. The core set of functions are perfect for getting the data of your blog posts, and even custom post types, however I needed to return data about some terms inside of a custom taxonomy I had generated.
Custom Controllers
The JSON API provides developers with a really easy method of extending the functionality of the plugin, you can do this by creating custom controllers. Inside of these controllers, you can define any functions you want to be able to use, and then build an array of data that you wish to return.
Creating your controller
In this example, I’ll be creating my controller to add a couple of functions that will return data about terms inside of taxonomies, however this tutorial can be applied to any concept of returning data from your database.
To create a controller, there are a few prerequisites you need to set in place. First, you’ll need to open up your theme’s functions.php file and add a couple of filters for each controller you wish to create, and something such as a PHP constant to define your root theme directory. If you’re creating a controller for anything other than terms, you’ll want to replace the instances of ‘terms’ below to something relating to what your controller does.
Next, you’ll need to create the functions for these filters. The function set_terms_controller_path() points to another PHP file where we will define our controller, this may need modifying to suit your needs.
With the foundations set for creating our controller, you’ll now need to create a new PHP file. You can place this anywhere in your theme, just make sure that the filename and path are the same as we defined above.
In your new PHP file, place this code, this will serve as our controller’s foundation – the name and description comments aren’t necessary, however I recommend using them as it improves the aesthetic of your backend by listing your controller with a name and description, rather than just listing the slug of your controller:
With our base sorted, you can now create your own functions to return data to this controller, which in turn creates your endpoint which returns the data you specify.
Take the following function for example:
The above code is a simple wrapper for the WordPress get_terms() function. The JSON API will handle creating the endpoints, this will be based on the function name, for example: http://yourdomain.com/json-api/terms/get_terms/, where json-api is the API reference you defined in the plugins settings, terms is the controller’s slug you defined inside your functions file, and get_terms is your functions name.
We are referencing the $json_api variable so we can check the query variables passed. This is useful for providing JSON formatted errors to your application rather than just breaking it if a specific condition hasn’t been met. Take the following returned error for example:
We can pass in variables to our functions in the form of URL parameters, like so: http://yourdomain.com/json-api/terms/get_terms/?taxonomy=sectors.
We are then getting the taxonomy from the query value that was passed in from the request, and passing this into the WordPress function. We are then returning the output of this to the JSON API. Here is an example of how the output may look:
You can expand this controller to suit any need you may have. If you have any questions, please don’t hesitate to leave me a comment!
Thanks for reading!