Why The WordPress REST API Must Be In Core

Josh Pollock - July 22, 2015

Recently I sat down with the developer of Morning Frame, a really cool analytics integrator, to help him figure out how to integrate with WordPress. I had to explain, as best as I could, the difference between the WordPress.com API, the Jetpack JSON API module, and the WordPress REST API.

Explaining, to someone with little experience of WordPress, the subtleties of how the WordPress.com API relates to the Jetpack JSON API module, and how the real one is the one that’s in a plugin, but it’s in a feature plugin, which is…

Yah, it got confusing.

The WordPress REST API has seemed like a forgone conclusion for inclusion in WordPress 4.4. Matt Mullenweg highlighted the REST API in his last State of the Word and all of the wonderful possibilities it could bring to WordPress.

While there has been ambiguity, it’s the topic that everyone wants to discuss at WordCamps. It’s the only reason why application developers from all sorts of backgrounds are looking at WordPress as the back-end for their apps. And the API itself the code is really beautifully with really lovely extensibility. It’s also in use on high traffic sites, has a dedicated team of “core” team of developers, 50 some minor contributors and is almost ready to go.

API Wapuu by Michelle Schulp.

This Wapuu by Michelle Schulp is adorable. Don’t break its tiny heart.

The seaming unavoidability of this becoming a feature of WordPress was snapped on Monday, when, during an epic 6 hour Slack conversation. During that conversation, Matt voiced his concerns about it, and questioned whether this feature should be a feature at all or if it made sense to stay as a plugin.

Nothing is settled, and no decision has been made one way or another, but now is the time to speak up if this feature is important to you and if you’re reading this site it almost certainly is.

I have no idea what is going to happen. I suspect, but have no idea, that Matt is playing devil’s advocate and challenging everyone to question their assumptions. Questioning assumptions is an important part of decision making. If that’s what is happening then he is being a good leader.

I followed the whole discussion, as this really important to me. I also built, yet another REST API add-on while I was reading, this time for WordPress SEO by Yoast :)

Having read the discussion, I am even more convinced that the REST API has to go in core. It’s a feature we need.

Either a RESTful API is a feature of WordPress — and it should be — or it’s not. And if it’s not, that’s a potentially devastating mistake for WordPress.

I wanted to share a few important reasons why I feel this way. I hope ya’ll will agree, and more importantly, share your own reasons why, either in a comment — now powered by Postmatic :) — or on Twitter or write about it on your own blog.

Update: An excellent place to share how you’re using the REST API and why it is important to you to have in WordPress core is in the comments on this make post: https://make.wordpress.org/core/2015/07/23/rest-api-whos-using-this-thing/

Now is the time to share why we need this feature in WordPress.

There Is No Existing Solution

XML-what?

Curiosity Mars Rover (From Wiki Commons)

NASA put a robot on Mars, we can put an RESTful API in WordPress.
Image via WikiCommons

All modern web apps, and most websites need a public-facing API. XML-RPC does not solve that requirement. XML is not modern, developer friendly or efficient. It’s also not what modern MVC frameworks consume.

One of the goals of the WordPress REST API project is to allow the phasing out of XML-RPC in core. A plugin can’t do that.

The modern web is being built with frameworks that consume JSON APIs. WordPress’ content editing tools, plugin ecosystem plus a RESTful API that is a huge boost to application developers.

Seriously this is 2015, RESTful APIs are what we use.

Yes, Jetpack offers a RESTful API, but while I am a big fan of Jetpack and use it on this site, I’m not going to run it on a site that powers an app. Nor is it extensible.

The Jetpack/WordPress.com API is awesome for the integrations with WordPress.com that it offers. But it’s not a developer’s tool.

More importantly, what I learned from working in the WordPress ecosystem is the importance of controlling your own data.

And the REST API can’t be a feature plugin forever, because then its not a feature. It’s another plugin. A feature plugin is a thing that only insiders understand. Beyond that, a feature plugin is a test for a new feature, not a feature. An exciting new feature that never leaves development, that reflects poorly on us all.

It Will Grow WordPress’ Marketshare

The WordPress REST API could democratize application development.

Only a REST API in core can dramatically grow WordPress’ marketshare by bringing app new developers into our ecosystem.

I get emails from non-WordPress developers several times a week looking for help integrating WordPress with whatever they are building. I’ve worked on projects where I didn’t know the language the actual product was being written in or didn’t even know what language it was.

Those emails from developers outside of our ecosystem, looking to use WordPress for their apps, they are coming because the REST API will be in core. If that doesn’t happen then the feature will be seen as rejected — and with good reason.

Growing WordPress’ marketshare, by making a better blogging platform and website builder to compete with Wix or Squarespace brings more users into the pool of users that may need my services, or buy my products. The same goes for most people reading this.

Walking away from having a RESTful API, and an incredible tool for building your own in WordPress is walking away from another set of potential users — developers. These are people who will need the services of qualified WordPress developers, a managed WordPress host, and the various services — backup, anti-spam, etc. that are provided by members of our community.

Having WordPress’ content management system available, for free, to app developers saves them tons of time and money. It means a quicker path to MVP, opening the door to more experimentation as well as a lower barrier to entry for those without financial resources.

The only suitable alternative is to roll your own RESTful API, which we all do. It’s a waste of time, and doesn’t contribute to a standard. WordPress’ job is to create a standard, sensible defaults, and the opportunity for customization. This is what the REST API does — gives us a set of well-done defaults and the tools to customize the API to fit our needs.

Plugins don’t codify standards for the WordPress way and they don’t give WordPress its common defaults — that is what WordPress does.

 

The sky. Photo by: Garrett Carroll

This is a beautiful photo of the sky. Beautiful things are important. Photo by Garret Carroll via UnSplash.

It Is Not The API Until It Is In Core

It’s either a feature of WordPress or it’s not.

Yes, the REST API could just be a plugin, technically speaking. But then it’s a plugin. It’s not a feature of WordPress.

Jetpack isn’t the social sharing, analytics, contact form, etc… plugin. It is a popular option. That’s fine, we don’t need standardization for what Jetpack does.

We need standardization for default routes. There is no other way someone can build a general app, one designed to integrate with any WordPress sites, unless there is a standard. By general apps, I mean content editors, backup and site management systems, all of which are rolling their own APIs right now.

I also mean the kinds of apps that don’t really exist yet, but I would love to build, that work across sites to improve management of specific features — social integrations, SEO etc. Seriously I have a lot of these ideas, someone DM me on Slack or Twitter, if they are interested in getting involved. Well, if the idea of a RESTful API as a feature of WordPress isn’t killed off that is…

It’s also very hard for plugins and themes to integrate with a feature of WordPress, that isn’t a feature. WordPress doesn’t have a plugin dependency system, it may one day, but that’s technical challenge that is going to take a lot of work.

The WordPress theme repository prohibits themes that rely on a plugin to work. There is a good reason for that: a theme should work with WordPress and shouldn’t bork a site if a plugin is disabled.

The REST API presents an opportunity to make better, more dynamic and offline-friendly themes. Until developers can deliver a REST API-powered theme that just works with WordPress it’s not going to be a smart business move for anyone to make.

There is a reason why there are very few WordPress themes powered by the REST API, and none are aimed at “regular users.” Nor should there be, a theme should work with WordPress, not be reliant on a plugin. A REST API-powered theme for general release is a non-starter unless the REST API is a feature of WordPress.

The REST API Has Institutional Support

A new feature is like a puppy, it’s cute now, but what happens when it shits on the rug?

My dog Josie begging in my kitchen.

This is my dog Josie begging for food in my kitchen. Don’t make me beg.

Most new features of WordPress, in some way are useful to WordPress.com, or some other Automattic product. That’s great, as Automattic, a large, stable, and well funded company has an interest in seeing these features maintained.

But WordPress.com already has a RESTful API, this new API is for the rest of us. Luckily WordPress is bigger than WordPress.com.

The WordPress REST API is in use on the sites of huge media outlets. These sites are developed by some of the best WordPress developers — developers with a strong history of involvement in our community.

TheWordPress REST API is in use on sites built by the big WordPress development agencies. The same agencies that contribute in a multitude of ways to our community.

This feature, developed by community members, a part from Automattic, a part from the core team, if it enters core, is a victory for the ideal of an open source community. If this project with an overwhelming amount of support doesn’t become  a feature of WordPress, what does that say about the openness of the WordPress project.

If the REST API is added to core, that is a lot of code that needs to be maintained. Code that needs to work with WordPress 5.7.

The WordPress API has passionate contributors, who will love it when it stops being shiny and new, because they love it and have a vested interest in it continuing to work.

It’s also really well done, easily verisonable, and has great unit test coverage. It’s not perfect, but it can be easily evolved and improved, which will happen if the excitement isn’t robbed from this project.

I Love It? Can We Keep It?

Forget the #wpdrama this is the debate that matters!

I’m not going to lie. I’ve got a lot of skin in this game. I’ve been writing a lot about the REST API for Torque, and building custom add-ons as well as contributing to the REST API docs. I do this because I want to spread the word and because I want to be a go-to person for REST API integration and customization. That’s how free software works — we contribute, create extra tools and educate — giving freely to establish ourselves as experts.

But we all have skin in this.

The WordPress REST API is already attracting new people to WordPress. Adding it to core will bring more. Rejecting it as a feature of WordPress says WordPress isn’t developer friendly.

Even if you never build anything with the REST API — those new people may be your customers or clients.

The WordPress REST API already helping us build awesome stuff. With it in core, we will build even more cool stuff. Rejecting it says “sorry no thanks.” It says we’re stuck in our ways and against modern trends in web development.

Even if you never build anything with the REST API — you are likely to use something built with it.

#wpapi4thefuture

I Use The REST API Because It Is Awesome. Hashbrown no filter.

If you’ve read the source for the WordPress REST API, and I have read most of it, it’s something you can be proud of having in the tool you use to make your living. If you’ve used the REST API, you know how awesome it is, and all of the possibilities it opens up.

We can’t walk away from this feature now, and that’s what happens if it’s not in core. If it’s not in core, it’s just another plugin — not a standard that can help us stop rolling our own APIs, or using XML-RPC.

It goes in core or it’s not something we can all count on being there and count on staying there. If it’s not in core, we’re going to be making insanely complex explantations to potential clients and users for years to come, and apologizing for something we could have had but didn’t.

We were all told the REST API was the future. Then we tried it and said “the future looks awesome.” Let’s not let go of that future.