The Interview

Interview Transcript

How did you get interested in the WordPress REST API?

I went to WordCamp Milwaukee in 2014, and I met Rachel [Baker] and Ryan [McCue], the co-lead developers of the project, and they were talking about this cool new REST API thing, and so was [Andrew] Nacin, the lead developer of WordPress at the time. That was the first time I got accepted to speak at a WordCamp, so I went, pretty much clear across the country from Florida.

I went to their talk where they outlined: “This is what it does, this is what we’re thinking,” and I thought “Wow, this is really cool.” And what’s cool about WordPress is that we use it as a safe space to learn new things.

What exactly is the REST API?

The REST API is a way of representing WordPress data that’s designed to be easily read by machines.

Fundamentally, the REST API is a data representation and a way of querying for data that’s designed to be read by machines. It opens up all the things that WordPress can already do—show some posts, edit posts, show users, change who a post’s author is—and gives you new ways of working with that data in your own data, your plugins, your themes. For me, that’s what’s really exciting about it: it’s a very modern way of working with this tool that we always had.

What are some good examples and use cases for the WordPress REST API?

For me, there are three categories of cool things you can do with the WordPress REST API.

There are a lot of use cases; in general it’s true that “developers care” about them more than general users. One of the reasons Twitter became so big is that it had this really easy-to-use REST API that allowed people to build applications that used Twitter data, and this is a similar story.

For me, there are three categories of cool things you can do with the REST API:

1. WordPress as the content management system for something other than a website.

For example, the Chicago Field Museum has touchscreens with more information about the exhibit you’re looking that. Who knows what that’s written in—it’s an embedded piece of hardware—but the backend is all managed in a local WordPress site. So the content creators are going into WordPress and editing that content, and that’s being consumed over the REST API into some other system.

2. Hybrid website/web apps, but it’s all in WordPress.

Traditionally, big sites put their blog in WordPress and the rest in something else. With the REST API, it’s easier to make a traditional website, but when you go to one particular URL, that’s a single-page web app, using Angular JS, React JS, or something like that. And then people take that further where they develop a mobile app using WordPress as the data store, something like Angular or React as the front-end, and something like PhoneGap to wrap that up into a mobile app they can then ship.

3. Making existing WordPress interfaces better.

being able to create a custom post editor for front-end submissions, with data sanitization, data validation, and authorization automatically handled by WordPress, is a big deal.

This means plugin and theme admin interfaces, and it also means front-end interfaces—and erasing that distinction. In the workshop we’re doing I show how to build a front-end editor for WordPress content, and what I point out is that the amount of server-side PHP code involved is about four lines and it’s just to load JavaScript. It’s wp_enqueue_script(), wp_localize_script(), and that’s it.

But what that doesn’t skip on the server side is data sanitization, data validation, and authorization: can this user actually edit this post? That’s all done in WordPress. Previously, I would have had to build all of that custom, and so not only does that save time and maintenance, it standardizes everything. The more we can take away from people’s individual responsibility for solving problems, the better.

So being able to create a custom post editor for front-end submissions that you can also drop into the back end, without worrying about anything on the server side, is a big deal. It’s just, “Install the REST API and write some JavaScript,” which is pretty different from the traditional way we would have looked at this.

Do you think WordPress’s heavily “posts”-based database architecture limits it as a data store?

I agree, although you can move data into custom tables. This also gets back into “Why WordPress?” and sometimes the answer is “No, Laravel’s better for certain things.” It partly depends on what your end audience is—but one of the cool things about WordPress is that there’s so much WordPress, in terms of pieces of the puzzle that are pre-built for you, in terms of people you can call on to work with on your project, in terms of learning and educational resources.

I know for myself as a self-taught or community-taught developer, it’s a lot easier for me. The first time I was learning Angular, I was also learning how Firebase worked. It was a disaster that never functioned. Because I’m familiar with WordPress, my second experience with Angular was actually improving the admin interface for our A/B testing plugin, Ingot. We rewrote it as a single-page mini-Angular app sitting in a WordPress admin page. I was learning Angular, but I already knew WordPress; all I had to do was learn Angular. And that’s a huge benefit to us in the community.

Let’s talk about the process of the REST API making it into core.

Minor history lesson. This is something that Ryan McCue was kicking around for a while. Version 1 of the REST API got to basically complete, and then said, “Okay, this is what we’ve learned, and now let’s do better,” and that led to version 2. That was finished enough to put in, in WordPress 4.4, the infrastructure for making custom REST APIs. This is in WordPress core, but what we don’t have is the automatic display of content—that was supposed to be in 4.5, but turned into a long discussion. It’ll now be making it into 4.7.

The merge proposal includes a proposal for WordPress to provide OAuth 1 for authentication, and the question is whether WordPress Core provides OAuth 1, or do we say, “There’s a set of authentication plugins” that let you choose between OAuth 1, OAuth 2, and other systems? That’s the main sticky point right now. [Note: This interview was conducted before the final decision to merge content endpoints in 4.7, and to focus on authentication for 4.8.]

For me, I’m an optimist that authentication can make it into Core, and I think it should. It’s better to say “If you’re running WordPress 4.8 or later” than to say “If you have an authentication plugin installed…”

Is v2 of the REST API “finished” in terms of breaking changes?

There are two main pieces to the current REST API: the infrastructure that went in in 4.4, which is stable, and the endpoints, which are still in a beta plugin until 4.7.

There are two pieces to this. The first is the infrastructure that went in in 4.4, and now that we’re a few versions out, and thanks to WordPress’s commitment to backwards compatibility, that’s likely going to be there for a long time. I’m also comfortable rolling out new features in my plugins that use the 4.4 infrastructure: it’s been more than a year, and most of the people who don’t update WordPress don’t update their plugins, either.

The infrastructure stuff is what you really need for most plugin development, since you’ll be adding your own endpoints. So I would recommend learning that stuff: how route declarations work, how the callbacks work, how the authentication should be done, sanization and validation—it’s very neat stuff, some of the better-written stuff in WordPress. From there, you’re good; you’re not relying on the REST API v2 Beta plugin.

The second piece comes in if, for example, you have an idea for a better way of managing posts. Now you are dependent on the plugin, which they’ve intentionally called a Beta, because they’re committed to getting it right, not to backwards-compatibility. There have been breaking changes in the Beta so far, but, like the 4.4 change, when that will solidify the endpoints go in in 4.7.

One cool thing about the way the REST API is built is that the endpoints are at wp-json/wp/v2. That “v2” means that in a few years you might see a push to build a new plugin that does things a bit better called v3. This is an opportunity we don’t really have in other parts of WordPress: you can’t do a “WP_Query v2” that exists in parallel to WP_Query. But we could have version 3 under development, and at no point does that affect the performance of version 2. I really like that for the future.

How should people learn the REST API now? What’s hard and easy to learn?

In general, there are two types of ways people like to learn this kind of stuff: some people like to read, and some people like to watch videos.

There’s also the question of what you’re trying to learn: are you trying to learn what all the endpoints do in the core plugin? Are you trying to learn how to make your own REST API endpoints? Are you trying to learn how to use a JavaScript framework to build something cool with this stuff?

I want to point out that you don’t need to use a JavaScript framework to do cool things with this stuff—you can consume it in PHP or some other language. That said, React JS and similar things are cool.

Text Resources

If you’re into reading, I’ve written about the REST API at joshpress.net, and a ton at Torque, including a free-to-download ebook. The ebook covers things like what the endpoints do and a few cool projects you can build with them—that’s really good introductory stuff.

Tuts+ has also written some cool stuff on getting started with the REST API. Lastly, there’s also really good documentation at v2.wp-api.org that covers the basics.

Video Resources

If you’re into videos, we have a course on the REST API at learn.joshpress.net. It covers what the REST API is, how to add custom routes, how authentication works, and the basics of using Angular to build a little app. We’re going to have another course coming out soon, which you can preorder, on being a better PHP developer in the world of the REST API: how to develop plugins and sites with good, solid, object-oriented PHP code that can be consumed the old-fashioned way—in a theme, in a shortcode, in a PHP function—and in a REST API.

Also, Roy Sivan has some really good courses on Lynda on using the REST API to build Angular apps.

So in general, go to learn.joshpress.net to get the first REST API course—it’s a good overview over three and a half hours. And once you have that basis, for something more practical and hands-on, look for Roy’s stuff on Lynda.

Lastly, most people in WordPress are tangible learners. I really recommend that you find a project that uses the REST API, but uses it as just one new piece of technology.

What’s the hardest piece of learning the REST API?

With authentication, the options get very convoluted, but you should remember that it’s all about “How do we set the current user?” Once you’ve done that, WordPress handles it from there.

That’s hard to answer, but let’s talk about authentication, which is one of the poorest-explained areas.

If you look in the code of the content API, all the permission checks are “current_user_can_X” which is like anywhere else in WordPress. That’s nothing new—if you’ve done WordPress development before, you understand this system. Where it gets tricky is: how do you set current_user?
If you’re using the REST API inside a WordPress site, then all you need to do is send a nonce on the action wp_rest, and everything’s handled for you. Go to the v2.wp-api.org documentation—it’s very clearly spelled out.

Now, what if you’re not inside WordPress? Now you have a lot of options, and there’s no one-size-fits-all. There’s OAuth 1 and OAuth 2, which are different but related protocols—both of which are a pain—There’s also JWT Token authentication, which is much simpler and is what I use; there’s a plugin for JWT authentication via the REST API that is very simple to use and is fairly secure if you’re over HTTPS. You can even write your own authentication system—there’s a filter that you can use to set the current WordPress user.

So the options get very convoluted, but it’s all about “How do we set the current user?” and then WordPress handles it from there. It’s easy to get distracted because we have so many options, but I think those options are good since none of them is the right answer one hundred percent of the time. Just don’t get into “I have to use OAuth”: OAuth’s annoying, and there’s no categorical reason why it has to be used. If you want to learn more, there’s also an entire section of my course on authentication that covers a variety of options.

Is there anything else you’d like to say about the REST API?

The REST API isn’t a magic bullet. Don’t think you “have to” use it, but think about it in terms of making stuff better.

Remember that you don’t always have to use it: it’s not the answer to everything. It’s not a magic bullet. End users want something cool, and I always encourage people to look at it that way: how can I show my clients something cool, and something that they wouldn’t expect out of WordPress? How can I use this tool to make my client’s end users happier, and impress my client?

Also, think in terms of, How can we use this to do something we couldn’t have done? For example, “For X we’ll build you a website, and for 150% of X we’ll build you a website and a mobile app. I’ll charge you more than I’d normally charge, but less than you’d pay two developers.” Or offering people a single-page web app without lots of page loads and with infinite scrolling.

Think of how to do things better, because that’s the point of cool new technology: to do things better, and to have more fun.

The other thing is what we can learn from this as a project. This has been a bumpy road. I hope we’ll be able to learn from this, because WordPress is going to need to support virtual reality in a year or two, and direct brain hallucination in a few years after that. How do we continue that WordPress is still the thing that works for everybody, and just works? I hope we as a community can learn from this experience, and the next cool thing is easier to build into WordPress.

Where can people find you?

My company is Caldera Labs. We make WordPress plugins, including Caldera Forms, a drag-and-drop form builder. You can also find me on Twitter at @josh412.