In Collaboration With:

WordPress as an external component in a Node.js application

The WordPress REST API changes what it means to be a WordPress developer. K. Adam dives into ways JavaScript and Node.js applications can be built to consume, augment, and complement WordPress.

You can view all videos as we release them on the A Day of REST video archive.

K. Adam White is a developer at Bocoup. You can follow him on Twitter, view his Github profile, or visit his website for more about him. His slides are available to follow along with this presentation as well.

Bocoup has built a number of JavaScript applications and consider themselves platform agnostic, but are big promoters of open software. They have built many Node.js projects and in the project K. Adam is highlighting with this talk, they utilized WordPress and the WordPress REST API in concert with Node.js. They were looking for, “the best CMS for Node.js,” and decided that perhaps WordPress could be that CMS.

The team at Bocoup were looking for options with a balance of extendability and a strong editorial flow. The options in the Node.js ecosystem, while good, weren't a good fit, and they didn't want to build their own CMS, so they decided to build a proof of concept with WordPress and the WordPress REST API — which were brand new at the time — to see if it could be a good fit as an administrative environment for their project.

Potential perils of using WordPress as an external API

The proof on concept with WordPress worked, but as the project progressed, they discovered areas where WordPress and the REST API had their downsides, and K. Adam has some takeaways that others may consider.

  • Caching content outside of the main WordPress data store is important so that the site doesn't go down if WordPress goes down.
  • Working with a not-yet-stable REST API was challenging, but “worth it to be involved.”
  • A lot of custom code was needed, both on the WordPress side for delivering the right content through the API, and on the front-end for receiving the data.
  • The WordPress admin has many links that assume you're using WordPress for the front-end, so they can break and the admin needs to be customized if your front-end is external.
  • They had to do a lot of “wheel reinventing” in all parts of the process. One example of this that K. Adam used was ExpressPress, an Express server with WordPress as the backend, which he calls very, “duplicative,” because he was forced to recreate routing, templating systems and how they communicate, all of which are already in WordPress but need to be done again for use in an external application.

Using the WordPress REST API for administration

They used the existing WordPress admin and a custom front-end, but K. Adam believes that building admins with the REST API will also help it evolve and develop to maturity.

He highlights Calypso — the editing and administrative experience — as an example project that will help propel the REST API forward. He also ponders what it would be like if the native WordPress admin were built on top of the API.

WordPress as a component

K. Adam believes that WordPress is more a component of the modern web than a platform for it. He referenced a previous speaker's notion that WordPress's road to further marketshare should perhaps be with WordPress being integrated into a site in some way, versus being the basis of one.

WordPress's way forward as an API

Instead of thinking of the WordPress API, “with this notion that it's this one big thing that we just need to use for everything,” he'd like us to think of it more subtly as an interface — which is, of course, the I in API.

K. Adam compares JavaScript — popular despite its imperfection — to the English language. And though it is far from perfect, “it rose to prominence not necessarily because it was the best tool for the job, but because it was there, in the browser.”

“JavaScript is capable of elegance, but it's built out of a lot of awkward parts.” Many useful and time-saving frameworks and APIs have been built to assist wrangling JavaScript — for example, jQuery. And while some folks may say it's preferable to skip jQuery in favor of “raw” JavaScript, K. Adam believes that often times it's better to take advantage of what existing APIs can give you for little to no effort, even if the result is imperfect.

K. Adam used these insights about JavaScript to relate back to the WordPress REST API. Specifically, he recalls how Bocoup was using WordPress for data, but it may not be as well prepared for some other parts; and he wondered how they could use other applications as components for various parts of the application. And that's when he came upon Ghost themes.

Ghost theming with WordPress

Ghost is a JavaScript CMS that was started by a member of the WordPress community, and even uses WordPress as a basis for some of its underlying ideas:

It happens to have a routing system and a templating system that takes  lot of inspiration from WordPress, and it happens to use Express for its server. So, given that it has a well documented theming system with things like a loop — which looks very familiar to a WordPress audience — maybe we can take these themes and put them on top of our WordPress content.

Given that Ghost's theming system aligns well with the goals of Bocoup's project, and it uses similar concepts to WordPress for how theming works generally, creating a connector between content creation with WordPress and routing and templating from Ghost wasn't as hard as you might expect.

The wrapper takes the content from WordPress and maps it to an object that Ghost understands and expects, and in doing so, is able to inject WordPress data into a Ghost site. It fits into the component driven ideology, because, “once we transform things this way, using various tools for their parts becomes a lot easier when you have a transport that's as robust as the WordPress API.”

You could take a concept like this even further, by fetching every Ghost generated URL, save them as static HTML files, and essentially turn the combined entity of Ghost, WordPress, and Node into a static site generator. He does qualify the experiment, thankfully, noting that though you can do these things, it doesn't necessarily mean it's something you should want to do. However, he wanted to show that it is possible.

WordPress REST API npm package

K. Adam has created a library for npm that uses the WordPress REST API:

This library is designed to make it easy for your Node.js application to request specific resources from a WordPress install. It uses a query builder-style syntax to let you craft the request being made to the WP-API endpoints, then returns the API server's response to your application as a JavaScript object.

The library is under active development and has full support for the endpoints in version 2.0+ of the WordPress REST API. It also has endpoint discovery for finding custom written endpoints by plugin authors, as well as supports HTTP authentication.

One of the roadmap items for the library is to have a client-side bundle that can be dropped in without a build process, as well as a query builder that can work with, “whatever data fetching library you might be using.” His intention is to encourage the WordPress community about tools that can be built, more than advocating specifically for the library he has built.

Custom solutions for custom problems

K. Adam believes the highest profile projects that utilize the WordPress REST API will be custom, with specific use cases that require a lot of custom code and endpoints to meet the criteria for a particular project. But he also believes that the majority of applications won't be so custom, and people will desire an “out of the box” solution where WordPress can stand in as, “the people's API.”

K. Adam would like for WordPress — via its very strong community — to help lower the barrier to entry for creating and accessing custom applications, and “expose these tools,” so that everyone working with them can benefit, and if we do that, “everyone wins.”

The videos at A Day of REST were shot and edited by Rhys Alexander. The conference was organized by Human Made, and you can stay up to date with A Day of REST — which is going to Boston — and learn about other potential future events. There were eight great talks at A Day of REST, and you can read my review of the event as a whole, and look out for the next video to be posted here soon.