WordPress REST API proposed for core inclusion in two stages

The much anticipated proposal for core inclusion of the WordPress REST API is here. Ryan McCue — the project lead — has proposed a draft for the inclusion process that recommends a two stage approach. He recommends that stage one would be an “infrastructure” inclusion, to occur in WordPress 4.4; and stage two would be the endpoints, and would go in WordPress 4.5.

One of the highlights from the proposal is the justification for the API, which walks through existing APIs to highlight the benefits of the new one. I really haven’t seen this reasoning so well described elsewhere, so I’ll steal it from Ryan in full (because it’s important to read) and ask forgiveness later:

WordPress already has external APIs: XML-RPC, designed for desktop clients; Atom and RSS feeds, designed for post syndication; and the venerable admin-ajax, designed for Ajax requests in the admin and frontend. These APIs all serve different purposes, but often have a great deal of overlap. In addition, these have all been stretched beyond their original intentions: XML-RPC now contains site management tools, RSS has been extended into the WXR export format, and admin-ajax is the catch-all of any sort of browser-server communication in plugins and themes.

The REST API builds upon the heritage of these APIs to provide better support today for using these, as well as laying the groundwork for expanded use in the future.

XML-RPC is the closest analogue to the REST API in terms of usage and capabilities. Originally designed back in 1998 to allow desktop clients to create and edit posts on blogs, WordPress has extended this with both other specifications (such as MetaWeblog) and with its own proprietary additions. Fundamentally, XML-RPC is built around Remote Procedure Calls (RPC), essentially a way of calling a function externally. It then uses XML to serialize the data for passing back and forth.

Unfortunately, XML serialization can be problematic at times. XML has lots of power, but support for custom entities and DOCTYPEs can cause parsing problems and security attacks, including billion laughs, and XXE exploits. (Currently, WordPress has to disable parts of the XML parser and apply regular expression replacements to be able to parse these safely.) XML is also very verbose, and represents data in a way which doesn’t map easily to programmatic data structures. JSON on the other hand is both concise and well-represented in memory, as it’s based on JavaScript’s native syntax.

The admin-ajax API is also very commonly used in WordPress, albeit typically only by plugins and themes. This is a very lightweight API that essentially acts as a mini-router. Typical usage of this API uses JSON, since it’s a browser-based API, but all usage is completely custom. A lot of the usage of this involves retrieving or updating posts on-the-fly, but due to its nature as simply a framework, these are done in completely different ways. This doesn’t lead itself to extensibility, and requires a lot of duplication every time developers want to get data in or out. We don’t want to replace all of admin-ajax though, since some use cases don’t map exactly: UI-related interactions or things like the Heartbeat API are great examples of this.

The REST API can help to supplant these uses. Our aim is to eventually replace the XML-RPC API completely, to act as a secondary import/export format, and to replace most (but not all) uses of admin-ajax. The REST API offers an easier to use interface than the existing solutions.

In short, the REST API is going to bring interacting with WordPress to a modern standard, and will benefit the platform tremendously.

A additional note that is quite interesting is that Ryan proposed that post-inclusion development remain on Github. It would be the first component of WordPress to truly sync Github and Trac.

Given the team’s experience with GitHub as well as Trac, we can bring the best of both worlds by helping integrate the two. This would also improve contribution for WordPress as a whole, and benefit the whole community. This will be especially important as we encourage more contributions from the wider community (client authors, for example).

Synchronous project management platforms for the REST API could provide a model for future WordPress components, according to Gary Pendergast:

The REST API team already have a well established workflow in GitHub. We’d like to experiment with combining their workflow with an (as yet undecided) method for syncing Pull Requests with Trac tickets.

By experimenting with a small part of WordPress, we can hopefully create a model that could be expanded to work for the entire WordPress project.

That would be very interesting indeed. This was promised, sort of, by Matt Mullenweg during WCSF a year or two ago, but really Github is still not the place where someone would report and discuss core WordPress issues, though official mirrors do exist.

Do keep in mind that this is a proposal, not a declaration. But it is a step forward, and the proposal will encourage a larger conversation to happen in core channels. If it is approved, we could see stage one in 2015, which would be a wonderful achievement. If you have feedback on the proposal process, now is the time to speak up.