WordPress Contributors Look for a Path Forward for the WP REST API

photo credit: Valeriy Poltorak

Over the weekend, discussion continued surrounding the direction of the WP REST API, as both Matt Mullenweg and Ryan McCue took to their WordPress blogs to clarify statements from last week’s status meeting. Differences of opinion are driving a heated debate about what constitutes a goalpost for the API’s readiness for core.

In a post titled “Chicken and Egg,” Mullenweg addressed the recent WP REST API discussion while sharing an anecdote from a book that covers history from the mid-90s hip-hop era.

I love the idea of Questlove realizing the song was missing something, and going back to the booth to keep working on it until it resonated with his target audience. A song that doesn’t stand up on its own wouldn’t be any better when bundled as part of an album. (Or Samsung would have the most popular apps on Android.) Fans hear the care and quality of each track, and they become super-fans.

Mullenweg relates it to considerations when building products for the web:

There’s this tension in everything we produce. Where’s the line to tread between 1.0 is the loneliest and a minimum viable product? Or is it about a minimum lovable product? Are we building a car with no air conditioning or a car with no wheels?

‘Pivot’ has become passé, but it’s much worse to assume that distribution will solve something core to your product that isn’t working.

Mullenweg mentioned the same car analogy during the meeting last week. In response to a commenter who asked for more clarification on how the analogy applies to the REST API, Mullenweg said the following:

If you want a good heuristic to use generally: there were decades of cars, millions of vehicles and drivers, before they had air conditioning. The core value proposition of a car is transportation, AC just helps you get there more comfortably. You didn’t need a car to get AC, you could have it in your house. AC might cause you to chose one car over another, but you probably wouldn’t walk or ride a horse if the car didn’t have AC, you’d just roll down the windows.

This begs the question, what constitutes wheels? Contributors to this discussion are divided on whether or not the existing endpoints are ready to be merged into core. The WP REST API team members, many of whom are already successfully using the API in production, believe that the endpoints are ready now. The current state of the API offers the ability to get content in and out of WordPress, opening it up for easier communication with other platforms, which many believe is the primary use case.

Mullenweg and others who joined the discussion last week are in favor of delivering something more complete, a REST API that supports everything available in wp-admin. This includes WordPress’ many site management features and would put the API several releases away from core readiness.

In a comment on our initial report, Drew Jaynes advocated what he believes to be a middle ground that provides a solid jumping-off point. This would involve resolving the missing pieces in the existing endpoints before merging them (items like password-protected posts, autosaves and post previews, and meta.)

“As I and others from the contributor/committer camp said in the chat, there can be a middle ground,” he said. “Whether that ends up looking like the four core endpoints alone, four core endpoints with some flavor, XML-RPC parity, or some measure of wp-admin parity, remains to be seen,” he said.

In a post titled “Progressive Enhancement with the WordPress REST API,” Ryan McCue outlined a full-on iterative approach that would push for distribution now and roll out more endpoints in future releases:

Progressive enhancement is our key solution to a couple of related problems: forward-compatibility with future features and versions of WordPress, and robust handling of data types in WordPress. Progressive enhancement also unblocks the REST API project and ensures there’s no need to wait until the REST API has parity with every feature of the WordPress admin.

McCue’s post goes into further detail of the REST API’s feature detection capabilities, which allow developers to easily detect support for features and build them in a forwards-compatible way while waiting for core support.

Is Distribution the Answer?

During last week’s meeting McCue said that continuing the project’s development as a feature plugin will do more harm than good. If the REST API is not allowed to ship without offering support for everything in wp-admin, the team would be forced to continue iterating on it as a feature plugin while simultaneously resolving difficult roadblocks in WordPress core. With just four major contributors operating at less than part time on the project, this requirement could stall the WP REST API indefinitely.

“We believe that the progressive enhancement approach is the best approach for continuing API development,” McCue said. “Progressive enhancement is a paradigm the REST API project ​must​ adopt, if it’s an API we want to add to (without breaking backwards compatibility) over the next 10 years.”

Mullenweg, who has led an iterative approach to development throughout WordPress’ history, is wary of latching onto distribution as the only way forward.

@Krogsgard No one is against iteration. It's: iterate in plugin with low stakes, or iterate in core, shipping to tens of millions of sites?

— Matt Mullenweg (@photomatt) February 8, 2016

The larger WordPress’ usage becomes, the louder its footsteps are heard. Iterating on the REST API in core, with distribution to millions of sites, may affect the web in ways contributors cannot yet anticipate. As they say, heavy is the head that wears the crown. The ripples extend beyond WordPress sites to the outside platforms that will also consume the API.

Contributors are still discussing the nuances of iterative development in core vs. delivering a more complete API. Meanwhile, adoption is stilted by the uncertainty surrounding the project and the fact that it still carries a plugin dependency. It’s not yet clear whether WordPress contributors will dig in and push for inclusion of the endpoints against Mullenweg’s recommendation or whether they will opt to spend more time polishing the existing endpoints. If the WP REST API team is required to ensure that the API can support a wp-admin replacement, it may not land in core until the end of this year or later.