WP REST API: Version 2.0 Beta 1

Hi there, we’re the REST API team. You may remember us from such releases as Version 1.1 “Hammock Hut” and Version 1.2 “S-M-R-T”. Today, we’re excited to announce the first beta release of version 2 of the REST API: 2.0 Beta 1 “Ralph Wiggum”. Go and grab it from GitHub right now, we’ll wait.

Over the past 9 months, we’ve been reworking some of the important internals of the REST API to improve extensibility for site developers, and usability for both plugin developers and client developers. We’ve codified some of our important internal conventions, added plenty of new tools for you to play with and simplify your development, and reworked some of the less fantastic parts of the API. We think these changes will make the API a whole lot better for everyone, and we’re excited to start getting your feedback on these changes.

One of the things that you’ll notice immediately when using version 2 is just how much hasn’t changed. There’s a lot of things that we’ve changed under the hood, but the fundamentals of the API haven’t changed up too much. Version 2 is a direct continuation of version 1, so most of the API will be instantly familiar to you if you’ve used version 1 before. We have a primer on the important changes since version 1, including a guide on migrating existing endpoints across to version 2.

Here’s some super important notes on version 2, before you get started:

  • No Backwards Compatibility: Version 2 is not backwards compatible with version 1. We have plans to ensure that a version 1 compatibility layer exists, but we’ve leaving that until the API has settled down fully before creating that. However, porting endpoints is easy if you want to give it a go.
  • No Forwards Compatibility: Beta 1 is also not guaranteed to be forwards compatible with future betas. Although this is a beta release, it’s still likely that parts of the REST API will change. However, at this point, the core infrastructure of the API is unlikely to change in a breaking manner, so internal plugin APIs are pretty solid. We reserve the right to break these in future though, so keep that in mind when updating.
  • Development Only: Due to the lack of forwards and backwards compatibility, we strongly recommend you do not run the beta in production environments. While it is possible to run it (both security and privacy have solid, thorough handling), any updates will likely break your site.
  • Run Concurrently: You can easily run both version 1 and 2 side-by-side, since the prefixes for all functions and filters have changed. This will require changing the URL for version 2 however, which can be done with the following filter:
    add_filter( 'rest_url_prefix', function () { return 'wp-rest'; } );

With all this said, we’d love you to test the plugin as soon as possible. We’re looking for feedback on every part of the API, especially the changes since version 1. If there’s anything that has made it easier or harder since version 1, let us know. We’re continuing to improve the API every day, and now is the time to let us know what’s important to you. (P.S. Did I mention we have an issue tracker?)

We’re excited for this new stage of the API, and we hope you are too.

#json-api, #rest-api