The WordPress REST API Plugin is a simple-to-use plugin that allows you to access your WordPress posts, pages and other data via a JSON-based REST API. REST APIs have grown in popularity in recent years because they are fast, platform-independent and easy to integrate.
WordPress is a powerful CMS with a ton of extensible features, so why use the WordPress REST API? I’ll let the authors of the plugin explain:
“WordPress is moving toward becoming a fully-fledged application framework, and we need new APIs. This project was born to create an easy-to-use, easy-to-understand and well-tested framework for creating these APIs, plus creating APIs for core … WP API exposes a simple yet easy interface to WP Query, the posts API, post meta API, users API, revisions API and many more. Chances are, if you can do it with WordPress, WP API will let you do it.”
Imagine integrating your site data with a snazzy new iOS and Android app or using the world-famous WordPress admin for the management of a custom application. The WordPress REST API enables both of these scenarios with a minimal development investment.
How do we use this fantastic plug-in? Let’s walk through it by building a simple and practical application: a website health dashboard that monitors the status of a list of websites. This application will be separated in two parts: WordPress utilizing the REST API and a NodeJS application for the health checks.
You’ll need a fresh install of WordPress. If you are looking for a simple development environment for WordPress, VVV provides a WordPress-focused development environment through Vagrant. If you’re new to Vagrant, the VVV Github page provides an excellent walkthrough in getting set up.
Once you’re up and running with WordPress, you’ll need to install the following plugins:
- WordPress REST API – https://wordpress.org/plugins/rest-api/
- Advanced Custom Fields – https://wordpress.org/plugins/advanced-custom-fields/
- ACF to REST API – https://wordpress.org/plugins/acf-to-rest-api/
- Application Passwords – https://github.com/georgestephanis/application-passwords
While the ACF plugin is not required for the WordPress REST API, it’s a very useful tool for managing custom meta.
Adding a Custom Post Type to the REST API
Once you’ve installed those plugins and activated them, we can get started by creating our own custom plugin. To do this, create a new file in the /wp-content/plugins/ folder called website-health-monitor.php with the following contents:
This is a very simple plugin: all it does is register a custom post type called “Site.” The most important thing to note in this function is this:
'show_in_rest' => TRUE
This allows your custom post type to be used by the REST API. Install your custom plugin and activate it. Next, we need to add a few fields in ACF: click on “Custom Fields” in the WordPress Admin and add a new field group, then add the following fields to the Site post type:
- url (Text)
- ping_status (True/False)
Now that you have your custom post type set up with these additional fields, add some data for testing purposes. The only field you really need to be concerned with is the “url,” all of the others will be overwritten by our NodeJS app.
Once you’ve entered data, you can test out the REST API by making a GET request to the following URL:
This URL will return all available posts of the type “Site.” You can use this same URL structure to see posts, pages and other custom types, like so:
To view a single item, you simply add the post id number:
Thanks to the great ACF to REST API plugin, we can view the additional fields that we added in Advanced Custom Fields by making a GET request to the URL with the following pattern:
Before we move on to submitting data from our Node.JS app, there is one last thing we need to do.
The WordPress REST API plugin documentation has a lot of great information about authenticating. Depending on the size and scale of your application, OAuth might be the best route as it offers the maximum security for clients authenticating to your WordPress REST API. For a small application like the sample one we are building, we’re just going to use the less secure Application Passwords plugin.
In Getting Started, we installed the Application Passwords plugin, which enables us to create (and revoke) application-specific passwords. To generate an application password, click on “Your Profile” under “Users” in the WordPress admin. At the bottom of the page under Application Passwords, enter a new app name and click Add New. Make sure to save the generated password; this is will be your only chance to do so.
Now that we’ve got our application-specific password, we can move on to our NodeJS app.
If you’re new to NodeJS, you can read a great summary and intro (as well as instructions on how to install NodeJs) on Modulus: http://blog.modulus.io/absolute-beginners-guide-to-nodejs.
To get started, you’ll need a simple package.json file in your application’s root folder:
Once you save that file into your application’s root folder, open a terminal window and simply type:
$ npm install
This will install our single dependency: the “Request” package. From there, we just add another new file “app.js” in your application’s root directory with the following contents:
Briefly, the NodeJS app goes out to your WordPress API to get the list of sites. For each site, it then makes a request to check if the site is reachable (by seeing if it returns a “200 OK” status). Once the request has been completed, the NodeJS app reaches out to our ACF REST endpoint and updates the data for the site. It then schedules itself to run again in five minutes.
We are now ready to run the app by opening a terminal window and running:
$ node app.js
If you check your data in WordPress you should now see that the data is being updated every five minutes by our NodeJS App.
Congratulations, you’ve just integrated an external app into your WordPress application framework! All that’s left to do is style your archive page for sites into a table layout (and maybe add some pretty icons), and you’ve got your very own website health monitor.
This was a very quick and simplified tutorial on how to get up and running with the WordPress REST API, but there are a lot more resources available to build much more complex applications using this great plugin. Check the plugin’s documentation for more information at http://v2.wp-api.org/.