There is mounting excitement over the WP REST API being added to core and rightly so! It is going to fundamentally change the WordPress landscape and open up all sorts of new possibilities. Developers are drooling over all the cool stuff they are going to be able to build. Exciting times!

But…

When it comes to using the REST API with themes, it may not always be the best choice.

TLDR

If you’re building themes for your own site or for a large client with a dedicated web team, go knock yourself with all the coolness you can build with the REST API.

If you’re building themes that will be distributed or will be used by small to medium clients that don’t have dedicated support, then you need to ask yourself if using the REST API is really the best thing for your users. Chances are you’ll be making their lives harder.

Note: I’m not talking about standard themes that just use the REST API for Ajax requests. That’s fine. I’m talking about themes that do things radically differently.

Background

I’ve been writing this post for more than a year. It started off as a post about why using Twig/Timber in distributed WordPress themes may be problematic, but the same issues exist for the REST API too.

Given the relative exposure of each of these, I changed the topic to the REST API a few months ago. There are many posts coming out now covering all the thing that you can do with the REST API and almost none covering what you shouldn’t do. In these situations, bandwagons are jumped and people start using things just because they can, even when it may not be the best choice.

Listening to an episode of the Post Status podcast the other day was the final push for me to finish off this post. They were talking about Twig/Timber (and Genesis), but many of the same issues will apply to themes built with the REST API. In fact, I decided to widen the scope of this article to include custom themes built for a client, after listening to their discussion.

A Story

I’m going to pause for a moment and tell you a story.

I used to run government websites. When I started, things were done in a government centric way. The websites told people what the government wanted to say, not what people actually needed. There was loads of information about what government had done. Profiles of staff. That sort of thing. Have you ever had to use a site like this to get something done? Not easy.

In 2010, I joined a new team. One that was building a Whole of Government website that was, gasp, user centric! We researched what users actually needed and gave it to them! When people wanted to publish content that users didn’t care about, we could tell them no! It took a while for the business areas to get their head around why it was important, but eventually they worked out that the site was only successful if met the users’ needs.

The point? It’s never good to lose sight of what the users need or to start putting your own needs first. Just because you can build a theme with the REST API doesn’t mean you should. You need to ask whether it’s right for your users – in this case the site owners who use your theme on their website? Is using the REST API helping meet their needs – or hurting them?

Reality Check

The REST API is super exciting to most of us. Every second WordCamp talk is about it.* Every second episode of the Post Status podcast is about it.**
*this statistic may be made up
**actually I think this one is true!

But here’s the thing: The vast majority of users don’t care about the REST API. Yes, even when we are talking about site owners rather than site visitors. They care about their business needs being met.

If the REST API helps with that, they’ll be happy. If it gets in the way, they won’t be happy. Either way they won’t care about the REST API itself, just what it means for them in terms of meeting their business goals.

Meet Joan And Bob

Meet Joan. She owns a pest control company with 6 employees. She knows that having a website is crucial for the business, so several years ago she got a local web development shop to rebuild the site. She paid a lot of money ($8,000!) but was really happy with it, especially the custom theme they built. That company went out of business and she’s still looking for a replacement. She’s not in a rush. After all, WordPress is easy and neice can help her out.

Meet Bob. He just started a tutoring business on the side of his day job. He wanted a website, but doesn’t have much money to spend on it. He doesn’t know much about web development, but he knows his way around a computer, so he decided to go the ‘do it yourself’ route: he got a cheap Hostgator account, installed WordPress, downloaded a free theme from wordpress.org and set it up himself.

Joan and Bob have some things in common:

• They’ve both heard that having a blog, rather than just a brochure-ware site, can help get them more business – so they’ve both decided to blog daily!
• They both use themes that make heavy use of the REST API.
• Neither theme has one of those fancy author boxes at the bottom of the post. They both want one!

What did they do? They both googled "how to add author info in wordpress" and clicked the first result. That took them to a WPBeginner post telling them how to do it. Step 1: Add some CSS to style.css. A bit tricky, but they both managed it. Step 2: They just have to do the following:

open your single.php and add this code inside your loop.

Hang on… There is no loop. Maybe there isn’t even a single.php. Hmm, this WordPress thing isn’t as easy as people say… 🙁

Examples

Here are some examples of how Joan and Bob would go following those instructions with some real REST API themes:

• Jack Lenox’s Picard Present theme: There is no single.php.
• Chris Hutchinson’s REST + React version of Twenty Sixteen: There is no single.php.
• Human Made’s Feeling Restful theme: There is no single.php.

Game over…

Don’t get me wrong – these themes are great work that are pushing things foward! But they are not for Joan or Bob and we need to remember that.

A Cornerstone Of WordPress’ Success

One of the strengths of WordPress, which has helped get us to the 25% market share point, is that it’s so easy to tweak and to get help with. Not sure how to do something? Don’t worry. There are millions of ‘how to’ posts out there. Can’t get in contact with your old web developer? No worries. There are hundreds of thousands of developers out there who understand how WordPress works.

Community support is a cornerstone of WordPress’ popularity. However, that’s built on things being done in a fairly standard way. As we enter the exciting new world, some of that will be eroded.

For users with a non traditional theme, many of those tutorials won’t work and they may need to get a more experienced developer to help them. Help will still be there, but it won’t be quite as accessible. For some users, this won’t be a problem. For many others, it will be.

We need to remember to design for the majority. Most WordPress users don’t know or care about the REST API. Many don’t have enough money to pay experienced developers to look after their site. Many will try to tweak the theme themselves at some point.

Using The REST API In Themes

I’m not saying "never use the REST API in WordPress themes". If there is a genuine need, then by all means use it! Just use it appropriately, keeping your users in mind.

If you do use it, then make sure you clearly communicate that with your users. If you’re developing themes for WordPress.org or a marketplace, make sure your documentation explains to users what they should expect. Try to keep the structure fairly standard and provide good comments in your code (or get ready for those support requests!). If you’re developing a custom theme for a client who may one day change to a different developer, do the same.

Both WordPress.org and marketplaces should consider how they make it clear to buyers what they are getting (ie flag to users that REST API themes are somewhat different). Neither wants to promote confusion. Marketplaces also have refunds to consider. There will always be power users who will understand what they are getting and need that – but that’s not the majority.

Final Thoughts

It’s straightforward really. Put your users’ needs first. Use the REST API when it’s appropriate. Don’t just use it because it’s cool! Maybe this is just common sense, but it needs to be said.

Do you agree? Disagree? Did I miss something? Let me know in the comments.