WP REST API Delayed, Contributors Facing Gridlock

The WP REST API team met yesterday in the #core-restapi Slack channel to discuss the status of the existing post, term, user, and comment endpoints. There are a few outstanding issues with these four core objects, which the team wants to tackle via a feature plugin approach instead of holding the API back from merge. These outstanding items include things like password-protected posts, autosaves and post previews, and meta handling.

“For now, we’re not going to support them, and will be working on them in a separate feature plugin instead,” WP REST API project lead Ryan McCue said. “Again, this will be an enhancement to the API in the future, and doesn’t block compatibility here.”

In September 2015, McCue and contributors outlined a merge plan for the REST API which brought the infrastructure into the 4.4 release with the endpoints on deck to follow one release later in 4.5. Contributors to the REST API believe that the project is still on track for this goal.

“Our proposal is that we ​merge the four core objects​ in the REST API with full read, create, update, delete support, with the more peripheral features to come ​when they’re ready,” McCue said.

Several WordPress contributors, including project lead Matt Mullenweg, voiced concerns about the REST API shipping without the features that have been temporarily spun out.

“I know it’s a minority opinion, but I would be pretty skeptical of merging a partial API into core,” Mullenweg said. “I think it would do a lot more damage than benefit.”

McCue contended that the team has been working towards shipping a product that can be progressively enhanced.

“The API is specifically structured around progressive enhancement, which is a key difference from many APIs,” he said. “Allowing clients to detect features and support them when they’re ready allows us huge flexibility.”

Does the WP REST API Need Full wp-admin Coverage?

Aaron Jorbin noted that while the four core object types allow for some innovative themes and content editors, they do not yet allow for full wp-admin replacements. This particular point was a deal breaker for several contributors attending the meeting.

“The cases where the current API covers today aren’t terribly interesting because they’re not really enabling something that was impossible to do before,” Mullenweg said. “It’s just a different approach to doing something that was already possible before. I don’t even think we have XML-RPC parity of feature support yet.

“I wouldn’t have included REST examples in the SoTW, or encouraged plugins to use the scaffolding, or even let the scaffolding in the last release, if I didn’t think it was the most promising thing out there right now,” he said. “But uptake definitely feels slower than I would have expected. It’s taken so long to get to this point, if we don’t pick up the pace, it could be another year or two before we get full wp-admin coverage.”

Despite the fact that the WP REST API recently had its own conference dedicated to it, most of the people who are building with it are those who are also contributors on the project. Adoption is not yet widespread, but this could be due to the fact that many developers don’t want to build on it until the core endpoints are officially merged.

“We’ve got a bit of a chicken and egg: without core adoption, potential API consumers are hesitant to take the plunge, but without adoption it won’t be tested sufficiently to be merged,” REST API contributor K. Adam White said.

“From a project point of view I’m not really excited about shipping an API that has ‘some assembly required,’ vs making the core release paired with interesting non-trivial killer apps (mobile apps, something calypso-like, big plugins using / supporting it),” Mullenweg said. “To me a complete API is one that covers everything that’s possible within wp-admin. A subset of that is a partial API.”

Multiple contributors on the REST API project, however, agreed that shipping with full admin replacement capability is unrealistic, especially after Mullenweg confirmed that it should support everything possible in the admin, including the file editor.

“We’re significantly more interested in getting read/write access to core types, so that we can interact with WP from a host of other platforms,” K. Adam White said. “I think that pushing everything off until it’s ‘Calpyso ready’ blocks myriad use cases before they can get off the ground.”

In response, Mullenweg asked why WordPress should support something in its web interface that isn’t supported through its official API. At the conclusion of the two-hour meeting he summarized his final proposal: “No partial endpoints in core. Let’s design a complete API, not half-do it and foist it on millions of sites,” he said.

This is a critical juncture for the WP REST API project. While most contributors seemed agreed on further iterating the existing endpoints and ramping up usage before merging them into core, attendees remained divided about the need to have full wp-admin coverage prior to merge.

WP REST API team members are squarely committed to iterating separately on peripheral features, but another contingent of WordPress contributors who joined the meeting yesterday are adamant about seeing a more polished API with better support for the admin. A plan forward has not yet emerged.