Cancel

Sarah Gooding

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

photo credit: Valeriy Poltorak
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.

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.

Category: ,
Tags:
18

18 responses to “WordPress Contributors Look for a Path Forward for the WP REST API”

  1. Josh Pollock on twitter regarding Matt’s objections:

    There are 2 big assumptions here – 1) That continuing to iterate in plugin is better than iterating in core. 2) That the features of the API that are proposed for 4.5 merge are going to pose a problem for core.

    I agree 100%. Matt has failed to make any coherent argument regarding the downsides of merging the API as-is. His post “Chicken and Egg” was incredibly thin compared to Ryan McCue’s “Progressive Enhancement With the WordPress REST API”.

    • I agree with that Josh guy:)

      But seriously, just beacuse Matt is making big assumptions doesn’t mean he is wrong. I was just pointing out where I think the assumptions are.

      I don’t see how merging the current default endpoints is going to cause problems for core moving forward. I have yet to see anyone make a reasoned case for why having this developer facing feature in core is going to hurt users. On the other hand, it is easy to make the case that we will see more developers creating more cool user-facing features, if we commit to making these default routes the standard.

      • But seriously, just because Matt is making big assumptions doesn’t mean he is wrong.

        Agreed. Apologies for conflating your thoughts with my own conclusions. In any case, I think discussing those assumptions specifically will lead to a more productive dialog about this issue. Currently it seems like people are talking around each other.

        • No need to apologize.

          I think naming assumptions as such is a key step to improving dialogue. I think one of the things that is really awesome about Matt is his ability and willingness to call out the assumptions that are being taken as fact.

      • Of course, those taking the contrary position to Matt are also making the same number of assumptions:

        1) That continuing to iterate in core is better than iterating in a plugin.

        2) That the features of the API that are proposed for 4.5 merge are not going to pose a problem for core.

        So that’s a tie.

        However, making these assumptions explicit won’t be much use if both sides seek to address them by speculating on the level of future usage. Where are the hard data?

        Oddly, the only data discussed so far were identified by Mark K and Timothy Jacobs in a short debate on a previous post on WP Tavern.

        In other words, I am not impressed by either side so far.

        • Probably, but I don’t agree with the usage argument though. The stats for low usage in plugins are artificially low — many of my plugins didn’t make the list. But, also it’s hard to ask a plugin with established userbase to alienate their existing users who can’t upgrade to the latest WordPress version for whatever reason.

        • @Josh Pollock,

          I agree with you about the usage argument. Data on usage are hopeless, and should be ignored.

          What I’m looking for is data about impact on core: weight of code, impact on speed, etc, etc. as compared to the specifics of what is gained by including particular endpoints.

          In other words, I am looking for the information that would enable proper risk assessment.

  2. A point of clarification which I think you covered well but maybe isn’t that clear to people observing from the outside: no one is proposing merging “incomplete” endpoints into core.

    The distinction may seem semantic but it’s important. A single endpoint (one for reading, creating and editing posts, for instance) may be considered “complete” on its own. It doesn’t need to be accompanied by every endpoint we can think of for WordPress (eg – comments, users, site options, widgets).

    An analogy that may clarify things for those that aren’t yet familiar with the “endpoint” terminology is posts. Custom Post Types extended WordPress in important ways. But WordPress was not “incomplete” when it only had Posts and Pages.

    Likewise, when the REST API team proposes the four primary endpoints for core, they’re not suggesting a bunch of half-finished work goes into core. Even with Drew’s suggested approach, the endpoints they are proposing for merge would only be merged when they’re deemed complete by the core committers.

    So the dispute is not over whether or not to merge something incomplete. The dispute is over whether to merge none of the completed features until every potential feature is completed, or to merge completed features as they’re completed.

    • That’s a very important point. Anything considered for merging into core must be ready for prime time. I’ve seen no valid argument to support Matt Mullenweg’s wanting to wait for all possible endpoints to be ready before merging anything. The four proposed endpoints cover a lot of what developers what to use the API for in the first place. Parity with all wp-admin features is not necessary for a minimum viable product.

      My two cents: If the proposed endpoints are merge-worthy, merge ’em. Keep everything else in the plugin.

  3. Analogies are used when you don’t know how to express your thoughts in a proper manner. Just look at Jesus, no one had a clue what his parables were about and he had to constantly explain himself :D. The disciples still didn’t understand. Though in this tale are the disciples the Automatticians, the other contributors or both groups? Who knows.

  4. I don’t know what the proper route is, all I know is that I just want to see the momentum keep growing for the API.

    The idea of the ‘minimum lovable product’ is something that I’m going to be thinking about a lot now.

  5. If I’m not very mistaken, the main difference of the two approaches is in marketing, isn’t it?

    WP API can be marketed as WordPress grown modern (or whatever term you prefer) to developers and decision makers even outside the community, but can it when it’s not “complete” yet? Complete in the sense you can do literally everything with it? Or in other words, would “outsiders” buy into the concept of complete endpoints instead of a complete API and consider the overall feature mature enough to work with?
    I know many agencies and developers do already, but those seem to be mainly the ones who’ve been following its development anyhow.

    On the other hand, trying to market a feature that hasn’t made it into core yet, is not marketing WordPress, it’s marketing a potential. It’s just not there yet, from an outsider’s point of view. Parts of it are in core, the rest is a darn plugin. Plugins break. Contributors can get sick. BDFLs can change their minds. Does this sound compelling from a marketing point of view?

    If I’m understanding Matt correctly, he wants to be able to take the whole cow to the market, not a couple of hoofs with a promise tagged on them. From the point of view of a project lead, I think that wish deserves consideration beyond arguments regarding development and the benefits of developers.

    Though I’m generally all for progressive enhancement, I’m not taking one or the other side here, just trying to highlight certain aspects of the problem that I think may be relevant for better understanding.

  6. To complete the analogy, if the current car market all have AC mag wheels and 300hp, it pretty silly to come to market with something that has none of that. Doubly so if you are trying to push it as the next great thing.

    REST API shouldn’t be included until it exceeds what we can already do through existing functions and plug-ins.

      • Yep, exactly :) The API is great in that it makes development easier, but since most plugin authors aren’t going to drop support for non 4.4 versions of WordPress, people are going to continue to use their own (simpler) implementations using the Rewrite API or admin-ajax.

        • Plug in authors will do it when it’s more reasonable to do so and more efficient. One of the great (and sad) things about WordPress is the relentless push forward. There are no real safe versions or safe stopping points, just a relentless move forward. The vast majority of active wordpress sites are on new versions, unless trapped by software restrictions.

          REST will come into it’s own over time if it proves to be a better way to program, a better way to develop, and stable enough for both. For the moment, it’s none of those things, and certainly doesn’t belong in core – YET.

  7. 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.

    In my opinion, this is not the choice on the table. For the record, the REST API Team support further iteration on the existing endpoints before being merged into core. That could mean waiting for the WordPress.com API team to use those endpoints in production, or gathering more usage feedback from others. I am strongly against merging anything before it’s been well-proven and well-tested.

    The proposal by the team was to include the 4 content endpoints when they are ready. We had a lengthly overview as to the progress of those endpoints, more details on what we feel is left to be done can be seen at https://github.com/wp-api/wp-api/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0

    Why these endpoints specifically? Because they are do-dependent for the most part. Shipping Posts without support for Taxonomies would not be that useful.

    Going for development of _all_ functionality (somewhere around 8-10 total data routes) should not be underestimated. It’s taken somewhere around a year and a half to get the current 4 to where they are now, and that was with 2 years prior art from Version 1.

    As someone who has been in the weeds of that implementation for a while now, I cannot over over-stress just how tricky trying to retrofit a consistent, coherent interface on 13 years of organically grown code and ideas can become. I’m looking forward to being part of the writing the implementation for the remaining (and majority) of functionality, however I don’t want to stop users and developers benefitting from what is already being built for another [several] years.

    One fairly large caveat here to address, probably: I don’t believe that implementing other endpoints (such as Plugins, Themes, Multisite, etc) will have any meaning full impact on the design of the Posts, Terms, Users and Comments endpoints that we already have. Therefore, I don’t see a good reason to not roll in endpoints as they are determined to be ready, in isolation. This may be where the disagreement lies.

    I think there is a very high bar for “ready”, which is why the team is not proposing that we merge _now_, there is still work to be done, but we feel what we have is getting very close.

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: