State of the REST API 2017

As we approach the State of the Word 2017 at WordCamp US, I think this is a good time to look back on the state of the REST API project and core focus over the last year.

2017 has been an interesting year for the REST API with highs and lows, and periods of intense development and slowdowns.

4.7

Immediately after WordCamp US 2016, WordPress 4.7 was released, which merged the second stage (endpoints) of the REST API. This was a major milestone for the REST API, and marked the culmination of our efforts over the previous 4 years.

In the months after 4.7’s release, we followed up by fixing bugs in the REST API, including two security bugs. One of these security bugs was a very serious privilege escalation issue, which was unfortunately caused by an unrelated low-level change in WordPress that the API hadn’t guarded against. A huge thanks to Securi, the security team, and to the hosts for working hard on mitigating, fixing, and deploying this issue. As the first large security release involving the API team, there was definitely much for us to learn, and we definitely learnt much.

With 4.7 representing a major culmination of the API team effort, most of the “core” REST API team (myself, Daniel, Rachel, and Joe) who lead the project pre-merge ramped down contribution. After years of intense effort on the project, we simply needed a break. As is the nature of open source projects, contribution is voluntary, and a massive thanks has to go to everyone involved for such a long time, especially to my co-lead Rachel. Thanks also to those who picked up the baton on the core work, including (but not limited to) Adam Silverstein, James Nylen, and K. Adam White.

The API has continued to improve in an iterative way throughout the year, with bug fixes and improvements from many members of the community. These have helped the API become more refined, stable, and most importantly, useful.

Core Focus

Organisationally, as we shifted from an independent feature project to part of core, the API also transitioned from a project to a “core focus”. This is a new concept and structure in WordPress, representing a large shift from the previous, release-driven product cycles.

With this change, our official goal was set as “getting first party wp-admin usage of the new endpoints, and hopefully [replacing] all of the core places where we still use admin-ajax”. Progress towards this goal throughout the year has been slow.

Part of the reason for this slowness has been a major drop in contribution. With our shift from GitHub to Trac, the number of drive-by contributions has fallen, with contributions coming more from regular core contributors. Additionally, with most of the core API team taking a break and moving on, the organisational and regular contribution has dropped massively. The combination of this drop in contribution to the API along with the ramp up in contribution on other focuses (Gutenberg in particular) means we are by far and away the slowest moving core focus, which has the flow-on effect of making us less attractive to contribution.

The scope of our official goal is also massive. As WordPress has grown organically from a static HTML admin to a more interactive interface, admin-ajax endpoints have grown likewise, with specialised endpoints added as and when needed. Our audit of the actions in WordPress showed 92 separate endpoints across 14 different categories, spanning every section of the admin. The organic growth of these has meant that a lot of the frontend code is tied specifically to the admin-ajax response, and vice versa, including passing generated HTML. In the process of investigating with these endpoints, experimentation showed that switching to use the API would essentially require rewriting the feature in order to use it.

Fundamentally, I think the core focus’ goal is at odds with the strengths of the REST API team. Our focus should be providing support to other teams (like the Gutenberg, Customiser, and mobile teams) and empowering developers to build on the API, rather than rewriting parts of the admin. The goal of switching the admin to the REST API is valuable, but it should be part of efforts to improve the user experience, rather than simply refactoring (especially when refactoring would needlessly break existing plugin functionality).

However, progress towards the goal across the entirety of WordPress has been good. One of the largest areas of admin-ajax usage is in the edit screen, where many of the admin-ajax endpoints will be replaced entirely through Gutenberg’s use of the REST API. Likewise, the Media endpoints will likely become legacy as the media library changes for use with Gutenberg. A significant portion of the endpoints are around themes, which are covered by the Customiser team’s efforts. The accessibility team is in the process of reworking the settings pages, which as a side-effect, will allow us to remove the settings endpoints; the Live Settings experiment also shows that we have the ability to improve the user experience here as well. All of these efforts move away from admin-ajax while also improving the user experience.

Moving forward into 2018, the REST API team needs to shift focus to the issues with the API, and focus on helping other teams do what they do best.

Our Big Issues

There are three big issues which the REST API should be focussed on to move forward: authentication, functionality, and empowerment.

Authentication

I’ve talked about authentication endlessly, and will keep talking about it until we solve it, because it is one of the largest problems we still have. Without a viable external authentication solution, over a third of the code in the REST API isn’t usable outside of the site. Imagine if Stripe’s API didn’t let you charge new credit cards, or if Twitter’s mobile apps only let you read tweets but not reply. This is the situation facing API users right now, and is the biggest reason the WordPress mobile app is not powered by the REST API.

Discussions at the Contributor Summit this year with the mobile team were fruitful, and we have a practical plan forward for rolling out select support for the official mobile apps while we work on rolling out general solutions. (As well as potentially enhancing the user experience significantly with things like magic login links.)

Efforts at the WordCamp Europe contributor day provided a massive push forward on OAuth 2 support, with the plugin now beginning to stabilise. A further focus here will allow us to build up the crucial momentum for development, and work with client developers.

OAuth 2 also provides a much cleaner way forward to solving the distributed API problems than our previous solutions. In the coming weeks, we’ll publish the first alpha versions of this new solution, which stays true to the original design goals of the first version of the broker while improving upon it in every way.

Functionality

With the push for merging the REST API, the nature of deadlines meant we had to push many features from the API to double-down on our core functionality. However, this means that the REST API is incomplete. In particular, we’re missing support for key objects in WordPress, including menus, widgets, plugins, and themes. We’re also missing some crucial functionality around existing objects, like post previewing. This means that while it’s possible to build apps on top of the API, some of the core functionality users expect is missing from those apps.

This has flow-on effects to the other core focuses. Incomplete support for drafts in the API has caused problems in Gutenberg, and the lack of support for appearance functionality causes the burden to shift on to the Customiser team. These fall squarely within our responsibility, and we’re currently letting them down.

Empowerment

The core of what the REST API does is empower developers to build things better and faster. To empower developers, we need to take the time to improve our documentation and provide better tooling. We have two fantastic API client libraries in the Backbone and Node libraries, and we should continue to push these forward while also helping to develop the client library ecosystem.

Key to this is ensuring that we are where our users are. Our previous contribution process on GitHub allowed us to benefit from drive-by contributions from developers using the API, and the momentum of Gutenberg on GitHub likewise shows the power of being where developers are. We recently migrated the developer reference to GitHub, and we need to look at further ways to embrace the external developer community here.

Additionally, we need to engage in more outreach with our users. While the user experience side of WordPress engages in user testing and outreach, there’s no equivalent for the REST API. We should be getting more client developers involved in the process, including the mobile team and developers of significant apps like Calypso and MarsEdit.

Our Future

While 2017 has been a tough year for the API, as we move into 2018, I think the state of the REST API is strong. We have the skills and the vision to push the API forward with our focuses, and empower other developers, whether inside the core development community or external.

But in order to enact these changes, make progress, and rebuild a strong contributor base, we need to make the fundamental changes to our organisation and goals to push forward.

We need to embrace our strengths and focus on the areas of highest impact. We need to listen to and work with our users on improving their experience and fixing their problems. And most importantly, we need to get more users by making the REST API more useful to more people.