When (and when not) to use the WP-API

Note: This was the write up a of a conference talk given in 2016, and should be considered of its time/not used for current dev practices or advice. Don't use WordPress.

The WordPress REST API is the future! This is something many of us have been saying/believed for about two years, but the future is now! Kind of. The REST API has (finally) been approved for merge into WordPress 4.7, meaning it will be available for use by everyone without requiring a plugin, as has been the case up to this point. Even without the official recognition (and with a not-small barrier to entry), lots of people and companies have done some pretty amazing things with the REST API. So I thought we'd look into the things people have done to get ideas for what the API will be useful for, and other ideas that might be best solved other ways.

For the purposes of this discussion, WordPress can be defined by an easy-to-use, extensible content management system. It powers a staggering amount of the internet, customized in an equally dizzying array of ways, and runs on PHP. The PHP part is often the biggest objection people have, for many reasons (not available in their stack, they don't like the language, etc.).

The two people who are co-leading development on the REST API (Rachel Baker and Ryan McCue) wanted to "future-proof" WordPress by allowing the development of new features and enhancements as well as people who were outside the PHP ecosystem to use WordPress.

That's a longer way of saying, "The REST API was invented so everyone doesn't have to rely on the traditional theming/plugin structure of Wordpress." The infrastructure for the REST API was implemented in WordPress 4.4. The first set of content endpoints (making the API actually useful to anyone) have been officially approved for integration into 4.7. For those still following along, that means that, with the release of 4.7, the following endpoints will be available for read/write:

Posts
Comments
Terms
Users
Meta
Settings (through Options)

Obviously, some of the specific data (such as User information and Settings) are restricted by user. The publicly available API will not return information that is otherwise locked-down in WordPress. Don't forget to install some sort of authentication plugin (Oauth1.0, Oauth2.0, JWT, application passwords, whatever floats your boat), as none made it into the 4.7 update (though they're aiming for 4.8).

In general, the API is going to be godsend whenever you're trying to work with WordPress and you want to break out of the traditional PHP/theme/plugin interface. In good news for the diehard PHP developers out there, you don't have to change a darn thing if you don't want to!

Specifically, I think the best thing going for WordPress right now is its ubiquity and ease of use in creating content. A ton of people have interacted with the WordPress editor at this point, and it's pretty intuitive to anyone who's ever opened Word. It's a fantastic tool to allow people to enter content. And plugins like Advanced Custom Fields or TablePress make filling out what otherwise might be tedious and confusing data (say, product details) remarkably simple. It's then up to us as developers to take that content and make it compelling to whoever's going to be reading it.

Previously, we've been restricted to using the traditional WordPress theme/plugin model — which is not a knock against it! People have built absolutely astounding things using it. But in order to do anything else required XMLRPC or writing your own custom endpoints, for which there was no standard and you'd have to manually include every piece you want.

Probably the biggest change that's going to hit is the ability to craft themes with zero use of PHP. Are you a React developer? Angular? Now, as long as the style.css is set up and loading in the JS files, you can create an entire theme without every having to write a single the_content();. A corollary to this idea is ...

The best part is, since WordPress is no longer chaining your front- and back-end together, it's extremely easy to use WordPress as just one part of your stack and use it only for specific needs it's well-suited for.

I work at the Penn State College of Medicine on our Hershey campus, which encompasses both the college part as well as the Milton S. Hershey Medical Center. The Marketing Department is responsible for both entities. As you can imagine, our tendrils reach all over the place: We run the public web site, the intranet, TV screens all over the place running a bastardization of PowerPoint (the content is a combination of calendar display, events, announcements and tons of other information), print flyers, print brochures, email marketing, signage, news, public events ...

Obviously, we're not going to be able to incorporate ALL of that into one place, and rightfully so — there are legitimate reasons InDesign exists, and we don't need to pull in print production to this process. But the ability to pull our digital together where that makes sense? I'm swooning. WordPress, making its content available through the API, could absolutely be the nervous system that gets all of our content going out to the various appendages from the central brain.

Enter the event in the backend, tag it appropriately, add the image. Now it's on the events calendar website immediately for people to find. Three weeks before it happens, we send out an automated email (using our CRM, not publishing out via MailPoet), push to the intranet and it goes up on the screens so everyone walking around can see it. And the information we send out is standardized and coming from the same location every time. We can integrate it wherever else it makes sense, and let the other systems are already in place work around/with the data.

And that's just my specific use case. Ryan McCue suggested touch-screen museum displays, but the more obvious implementation comes from ...

I'm sure at some point between 2009-2013, we all encountered the "Download our app!" website on a WordPress site that was little more than a basic blog. Someone (many someones, actually) decided that every website should have their own native app.

The easiest way (short of legitimately scraping the content from a website, which is time-consuming/hard) of doing this involved picking up one or more RSS feeds from the site in question and displaying it in a questionably-slightly-easier-to-use format. I worked for a publisher who went through more than the three companies mentioned by link earlier on in this paragraph, and I can tell you there were many aspects that drove us absolutely nuts, almost all related to customization.

We were allowed one (!!) image per article, because that's the standard featured image RSS feeds pump out. We weren't allowed to use JavaScript because they didn't know/didn't care about how to accurately parse the CDATA, and anyway they didn't have the right libraries loaded (or weren't willing to let us load libraries on the page). What we wouldn't have given for the ability to ship them a standard set of JSON, along with whatever custom parameters/images/etc. we wanted, and told them to design for that.

Luckily, even though this is about to get much easier for the average user, I think we as a society will be able to dodge the "have a WordPress site? Get a native iOS app up and running in 10 minutes!!!!" hucksters, simply because most people have already figured out that there's no real advantage (financial or otherwise) to having an app unless you have a reason to have an app. (Also, someone's already doing this.)

But imagine the people who DO need an app. Suddenly you can pull all your product information out of WooCommerce with ease and set it up to support native purchases using the Apple App Store or Google Play Store right on someone's phone (or the Windows Store and Mac Store, I guess, if you're into that sort of thing).

While most of us rightly blanch at the "advantage" of giving someone 30% of revenue, it's simple fact that for a lot of people that defines online shopping. That specific distribution model isn't going to work for anyone, but the ability to liberate information from the core install (and update it back in when something changes) opens up the possibilities for native applications the same way it does for non-PHP languages on the web.

While I will sing the praises of the content editor all day long, I give a deep shudder of foreboding when contemplating what permissions levels to set up for client users. Naturally, they all want to be admins ("It's my site, after all"), and all I can think about is how quickly they'll try to delete plugins, or change the theme ("it's cooler!"), or any number of problems. That doesn't even get to the non-project owners, who still want admin access, or who get lost because "I couldn't find that post!" (because it's a page).

With the endpoints we have now, we will be able to more easily only surface to people exactly what they need to be monkeying with. A content editor can get in and see the content editing screen, and no more. Even better, you can create detailed experiences for users at scale where they can manage their account information without having to drop them into the WordPress backend. Or, you can integrate some of the WordPress account information into wherever the user already is (say, in your ASPX-powered webapp's user screen). The key, as is the recurring theme here, is external extensibility. No longer are we confined to the WordPress sandbox. Speaking of which ...

I'm unapologetic in my love for the WordPress editor, but I recognize that it's not a tool that's going to work for everyone in every situation. Some people really need to see how the content is going to look before they feel comfortable with it, and now they can.

Front-end editing just got a LOT easier. Scrolling through your site and see a typo? If you're logged in, all you need to do is the "edit this page" link, make your edits, save the page, and continue scrolling on. Similarly, this makes applications similar to Calypso available without having to run JetPack. Now you can customize a WordPress iOS app to manage your posts and your custom fields, without having to worry about marrying everything up as you try to sync back.

Many stores (think Sears, or Verizon) now have their employees wandering around with tablets for various reasons: mobile checkout, customer service triage, etc. Let's take customer service triage: one WordPress install, an API-powered screen showing who's registered/approximate waiting time/whatever, backed by a native (or web-powered, doesn't matter) app running on the representatives' tablets that allows them to register and manage the queue.

The exciting part of this is absolutely not trying to get Verizon to replace their system (honestly don't care), but rather the ability to bring it to your grocery store for their meat counter, or maybe your local independent bookseller who wants to showcase different things on screens around her store. It's making the implementation easier on a smaller scale, cheaper, and growing the ability for people who already have an existing skillset to take advantage of it.

The second generation of the web (web 2.0, whatever you want to call it) was built on sharing data and user generated content. There have always been ways to integrate this into WordPress, but a full extensible API blows that out of the water. When I worked at a newspaper, user-submitted photo galleries did huge traffic for us, but we were using a platform that wasn't really designed for photo galleries (and we were going to stop paying for it).

At the time, I built a wrapper around the SmugMug API, but if I had an API for WordPress available at the time I probably would have used that instead. Imagine a drag-and-drop box where you put your photos in, tell us the captions, and they're automatically uploaded to the backend and ready for us to examine and approve them. All of the authentication, administration and admin work would have already been handled out of the box. It's not necessarily creating a whole new paradigm for the internet, but it does extend WordPress' capabilities to meet existing needs, and make it easier on everyone.

Most of the implementations we've been talking about thus far are focused on getting information out of the WordPress install for various purposes — one good one that publishers might want to focus on is AMP, Facebook Instant and Apple News pages. Since you can now grab your data via the API, pushing the information required by those services just got a lot easier. But we're talking about a full REST client, here. Incoming signals can be gathered from whatever other services you're collecting from (Facebook, Twitter, FourSquare, whatever), pushed back into the WordPress database for storage (and then extracted back to whatever you want using the same API).

Supporting WordPress just got a whole lot easier. Doing basic work/upgrades on a bulk scale have gotten easier and easier with automatic updating and WP-CLI, the REST API (if extended to the full use that its founders envision) could accelerate those changes by orders of magnitude. Enter RESTful WP-CLI. This project (which is in very early stages and, as its README warns, "breaking changes will be made without warning. The sky may also fall on your head.") is the type of innovation supported by the API that will save all us tons of time in the future. It automatically extends the REST endpoints into WP-CLI, allowing you to make the same changes from the command line.

The best part is, these tools will allow us to gain benefits even without expensive retrofits of existing sites. I'm certain there exist now organizations that run more than one WordPress installation that's not on multisite (for whatever reason), and don't have the time/money/internal political clout to change that. Simply through core updates to WordPress and the installation of a single plugin (RESTful WP-CLI), you could write a batch script to SSH into your WordPress host(s) and automatically add or delete a user the next time your company makes an HR change, and only have to do it once.

Right off the bat, the REST API will give us numerous ways to automate certain processes, and that number will only grow as the API gradually extends/eats the rest of WordPress' functionality.

It's not all upside, of course. Due to inherent limitations in the current implementation (lack of access to menus, single authentication option), not everything is going to feasible or wise in terms of build-out.

As of when the REST API is integrated into the core, there's not full wp-admin parity baked in. If your project operates outside the traditional theme model, basic structures and actions we've taken for granted such as the permalink and post previews available to users via the backend will no longer work unless the developer goes out of their way to reimplement the basic functionality.

Similarly, menu management is not going to be baked-in, at least in 4.7, which means you're going to need to do a little work (API Menu plugin) or a lot of work (recreating it however works best for you by hand) in order to get those things working. If you're just feeding information into somewhere else that's managing those things, no sweat. But if you're running that information into an iOS app, for example, you're going to need to deal with in one way or another, and the way people are used to (Appearances > Menus) isn't going to work.

That being said, the biggest caution flag I can see for developers is wanting to use the new API where it isn't necessarily needed. As mentioned several years ago in the TL;DR, maybe the project you're working on is specifically so you can see how the REST API works. If so, great, go nuts.

If, however, you're just trying to get the job done and you need to surface related posts inside a regularly-built theme, make sure you actually need to be calling those in via the API versus just including a custom loop in the footer, or something similar. I don't know if most of you know this, but developers of all stripes have a tendency to jump on something and use it for their next project because it's new, or someone said it's faster, or (often) just because it exists. The API enables us to do a lot of cool new things, but it doesn't necessarily need to replace your entire existing workflow. Use the tools best for the job at hand, and plug in new ones as necessary.

While this whole post has been API cheerleading and the ability to stop relying on PHP, I nonetheless want to caution people to think before implementing everything on the client side. There are many useful additions, hacks and modifications you can make on the server side to speed up the client side. Filters, long a valuable asset in the theme/plugin builder's toolbox, are even more so when it comes to the API. The large number of hooks available give you options, and it's up to you exploit them.

A project I did had a number of Advanced Custom Fields attached to a custom post type, including an image (with caption) and a relationship field to another post. With the proper hooks, I was able to transform the single call for an "event post" type to include the image, caption, the full content of the relationship post, and all of its ACFs. One call, all the info I needed (and I did need all the info every time I called it). A roundabout way of saying that just because PHP isn't necessarily going to be what you use to build the majority of the project, it doesn't mean you should discard it entirely. Your current WordPress skills aren't going by wayside, you're just finding new ways to augment them.

Examples mentioned

Resources

Github Repo - The repository for the questions theme from php[world]
Plugins - WordPress plugins to extend the REST API
Ionic — a mobile UI framework (Angular-based)
Vienna — iOS native editor for WordPress (React Native)
WP REST API React/Redux helpers — data-management helpers for React and Redux as Node modules
node-wpapi — WordPress REST API client for JavaScript