There’s a lot of weight to shoulder for the WordPress REST API project. It has a lot of hurdles to overcome and a lot of doubters to win over.
I’ve been silent about it, thoughtful about it, and questioning about it. I personally want the REST API if, for no other reason, than once it’s in-core, we can set the XMLRPC on fire. Which means…
My MVP – Parity with XMLRPC
That’s right. If the REST API can do everything that XMLRPC can do today, I think that part of its code needs to be in Core today. Get it in. Get people using it. I don’t think the measurements of how many plugins are using the REST API are a valid argument, since you get these numbers (roughly):
- 115 plugins use XMLRPC
- 25 plugins use V1 of the REST API
- 21 plugins use V2 of the REST API
Now, this is not the right measurement because looking at both XMLRPC and the REST API, we are not clocking the number of plugins but the number of sites – non WordPress sites even – that are calling these features. And that is a number that cannot be measured. There’s no way on the planet to really know for sure how many people use those features because, for the most part, they’re not doing it within WordPress. All the plugin scans will tell you is people who are extending it, for the most part. WooCommerce, Advanced Custom Fields, those are plugins adding their own endpoints and hooks.
And those, yes, are important. But more so is the real-world.
Can we detect how many WordPress sites are using the JSON API? Not really. Sure we could probably violate trust and get a list of every site that’s asked for an upload or install of the plugin, that wouldn’t tell us who has it active and who is using it.
We’re Not Ready (Until We Leave Beta)
We’re not wrong to be cautious about this. There’s a freedom a plugin has that a core feature does not. Once the REST API is in core, it’s done. I don’t mean development or innovation stops, I mean we can no longer make breaking changes.
While we believe the API is now stable enough for public testing, we may continue to break the API in the future as we improve it further. Only use the API in development, and do not use version 2 in production environments.
That’s what the documentation for Beta 1 says. And when I look at the changelog for 2.0 Beta 12.0 (released February 9, 2016) I count six changes labeled ‘breaking change.’ That’s bad. I hesitate at saying it’s deplorable, as I understand why it’s happening. They’re iterating fast and hard and trying to get to a place where they’re ready.
That said, this is a real world problem, as Eric Mann expressed in a series of Tweets:
My client installed the REST API before it included post meta. We had to build a bunch of custom work to support meta.
Then the REST API updated to include meta and broke our integration. I spent a chunk of hours refactoring to compensate so we could update.
Now, apparently, the REST API is pulling that meta support out and putting it in a separate plugin …
Yet people still criticize me for saying I’m wary of placing too much dependency on the stability of the API …
Eric’s point is a good and valid one, and it actually supports both ends of the argument.
The REST API is too much right now. It’s too much of all the things, and pulling meta out and letting it iterate quickly is a good choice. That said, the rest of the API needs to consider the same things. What’s done? What’s ready and locked and will not be ‘breaking’ changes? That should be ‘stable release #1’ and that goes into core.
From that moment on what’s in core cannot not receive any breaking changes. Lock down: These are done and will not be broken. Give the developers your promise in blood that this is what it is.
WordPress is backwards compatible for a million miles and frankly the REST API has not been. So make it. Put it in stone. But the REST API plugin itself is really too big to continue developing as it has been, and that’s to it’s detriment. It’s simply not sustainable the way it has been because it’s trying to serve two masters.
On the one hand, it wants to grow rapidly. On the other, it wants to be secure and safe and solid and ready for code.
But right now we’re stuck in Beta, and that hurts the perception. Also we’re still breaking things, and that hurts adoption. No one wants to start using a beta product that changes things in a way that breaks their sites. No one wants to use this for clients yet.
I Propose a “Release Candidate”
Go back to my first point.
Parity with XMLRPC. That’s all the REST API core plugin should be right now. Pull out everything else and slap the designation “Release Candidate” on there. You do not break things in Release Candidates. This candidate is your candidate for core inclusion. When it’s good, that goes into core and we close the existing plugin. Of course we do one final update to notify people ‘Hey, this is included in core now! Woohoo!’ It’s called ‘disabling’ the plugin, and anyone who has a feature plugin thats been moved into core, if you want it disabled, contact the plugins team. We will be happy to retire you plugin.
What about everything else? They get punted out into their own mini plugins. Like meta, they can be iterated and they can break all they want until they hit Release Candidate.
You see, that Release Candidate is your promise that you believe you are ready to go. Everything works the way you want it to, everything is ready for real-world testing. No more breaking changes.
In Hindsight
Looking back, I think the REST API is a perfect example of why the Featured Plugin system is both perfect and problematic. We are trying to simultaneously treat development like a plugin (fast, light, and iterative) and like core (adaptive, backwards compatible, and reliable). The whole reasons we started breaking out things like MP6 into Feature Plugins has come home to roost and shown that the idea is solid, but the methodology needs to be more set in stone as to what they should and should not do.
For a Featured Plugin, Beta is the time for breaking. RC is the time for testing in the real world. We need to be more firm about what we will include in our Featured Plugins and what we will not. We need to be harder on adding new features. We need to say ‘No’ a little more, and let things be developed outside of the plugin.
We need a plan that includes the retirement of the plugin when it’s job is done.
