If you go to a WordCamp and spend anytime around developers, it is hard to not notice the excitement around the new WordPress REST API.
The REST API team just released version 1.2 of the plugin, which they are continuously developing with the goal of merging it into WordPress core.
It’s a big project, much bigger than Ryan McCue—who, along with Rachel Baker, leads the project—ever thought it would be. I recently spoke with Ryan about the challenges of such a huge project and about the complexities in creating a “universal API” for every WordPress site, as well as the plans for the core merge.
Version 1.2 and backwards compatibility
Version 1.2 of the plugin is the last planned major release of the REST API as a plugin. The team is now focused on version 2.
Since the release of version 1, Ryan has been committed to supporting it and ensuring backwards compatibility—something that he and the REST API team are still committed to.
Version 2, the code that will merge into WordPress core, will not be fully backwards compatible with version 1, however, the plugin will continue on as a backwards-compatibility layer. That way anything developed using the plugin version, as long as the plugin is active, will work once the REST API is in core.
“We’re not going in and recreating this from scratch, and we’re certainly not breaking things unless we have to, so porting things over from version 1 to version 2 will be simple,” Ryan said in an interview.
In version 2, all routes will now be prefixed. Core will use a “wp” prefix and all custom routes will have their own prefix. In addition, the “wp-json” prefix currently in use for all routes may go away entirely. Sites using the plugin will of course get the older wp-json routes rerouted to the new routes once they’re in core.
“The idea is that externally, to anyone using the plugin, that our compatibility layer will make it look exactly the same to anyone using version 1.2. So version 1.2 is kind of like a fixed point in that regard,” Ryan said… “But internally, it will actually use version 2 and core infrastructure… so code written for version 1 can automatically benefit from any bug fixes that come out… and still have security maintenance… and we don’t have to support two versions.”
The core merge: possibly in two phases
Ryan hopes to have a usable version of version 2 within “the next month or so” to be released as a beta. The version 2 beta will be used as a merge proposal for core and, ideally, it will be merged into core in 2015.
The REST API codebase is essentially split into two parts: The first is the infrastructure for creating a RESTful API. The other part is the default endpoints it provides.
It is possible that the infrastructure will go into core first and then the endpoints will be added at a later date. If that happens, the infrastructure will be labeled initially as an experimental API. This would mimic how the Heartbeat API was introduced slowly into core, over more than one version.
The universal API
I asked Ryan about the challenge of making a “universal API” to be included in so many sites. He said that the biggest challenge is balancing all of the different concerns. Adding the default endpoints to core has a lot of complexity in terms of ensuring the right data is there, and balancing the varied and sometime competing concerns is a major challenge. This why getting it right has taken longer than expected.
He sees two primary core use cases for the API—both of which have conflicting needs.
The first use case is what he calls “service developers.” An example of this type of user is a news organization wanting to create an app based on their website providing API data as a service to the app. These users are more likely to use custom endpoints. So, for them, the infrastructure is more important than the default endpoints themselves.
A good example is Wired Magazine. Wired recently replaced multiple WordPress installs with one install, linked to multiple front-ends via the REST API. Ryan’s favorite part about this project is that the REST API will allow developers to choose their own way of working with WordPress. No longer will developers have to use a theme in the traditional way. They can use the JSON data anyway they want.
“That’s one of the use cases I really like,” Ryan said. “The fact that someone who doesn’t know WordPress that well can go and start creating frontend websites with this… It expands how many people can use and develop for WordPress.”
The other use case Ryan predicts is WordPress mobile apps. For these cases, the goal is to make the API work “consistently across every site in existence.” This use leads to an impossible expectation of the same data being provided from every site.
“Some of these problems we don’t want to try and handle because there is way too much there,” Ryan said. “The flip-side of all of this is that even if we know the sites have the same data, they may not have the same fields… We are trying to work out the best balance… between the flexibility we need to allow for plugin developers and the strictness that clients need.”
The ever-expanding scope of the REST API
Ryan has been working on the WordPress REST API for a very long time. To give you an idea of exactly how long that is, when he started, he thought it could be included in WordPress 3.6. The longer time frame for this project than he originally anticipated is not just because he underestimated the amount of work, but because the scope of the project has grown so much.
Originally he saw the REST API as ” just a way to get at the underlying data in WordPress and not much more than that.” Some of the code from the first release, which was very minimalistic, and handled a much smaller amount of data, still exists to this day.
The limit on just the four core objects—posts, users, taxonomies, and meta data—was decided early on, once the project grew. That’s limiting, but it sets up the REST API once it is in core to cover options and other data types.
Like all of WordPress, the REST API is designed to be extensible. The infrastructure for handling the rest of the data types, or doing whatever you want as a developer is there.
“The infrastructure of the API itself, supports basically anything you can throw at it. If you take away the core endpoints, it is essentially a framework for building APIs, and you can build those however you like,” said Ryan.
In his mind, the biggest misconception about the REST API project is that people are “going to see it as a magic bullet that solves all of these problems.” For example, generic response handling. A mobile app can’t automatically handle every single response that any WordPress site will be able to send to them. Solving the problem of a generic API hasn’t been solved and the WordPress REST API will not solve that problem.
“We want to allow this flexibility to plugin developers,” Ryan said, “plugin developers also have to understand that with the flexibility they are granted the have to take into mind things like this, and it is tough to convey this, especially for service sites… Trying to convey to people that they can remove endpoints, but they need to be aware that this will break stuff. Adding data to a response will be easier to do, as its not a big problem for clients, but it will be harder to remove data that is expected by a client.”
Forward the foundation (for your own API)
Ryan and more than 50 contributors are tasked with adding a RESTful API to tens of millions of websites. These are sites that they do not know the data structure of, or the needs of. In other words, it’s a huge task.
What I hadn’t understood personally before my conversation with Ryan is that this project isn’t just about creating a perfect API that works for tens of millions of sites. It’s really about adding a standard set of tools for anyone to make their own API, as well as a totally functional, but generic API.
The REST API is shaping up to be an awesome reflection of WordPress itself. WordPress is a tool that provides a basic starting point for a CMS in five minutes or less, which can be expanded on pretty much infinitely.
The REST API is no different. It provides a fully functional API out of the box, ready for anyone to use, with all the power needed for site and plugin developers to easily customize.