WP REST API: Version 2.0 Beta 9

For the last REST API release of 2015, we bring you: 2.0 Beta 9 “You Don’t Win Friends With Salad”. Download it from the plugin repository or from GitHub.

Should I use 2.0 Beta 9 in production?

This is a great question. I (Daniel) will do my best to answer from my perspective — Ryan, Rachel or Joe may have different opinions.

As many of you may already know, the v1.x branch is essentially deprecated and only maintained for security and major compatibility issues. Even its latest release, v1.2.4, still includes some annoying bugs. The v2.0 Betas introduce aton of new features, functionality, and general improvements. But, there will never be a formal v2.0 plugin release — v2.0 will be endpoint inclusion into WordPress core.

Right now, we’re doing our darned best to get the endpoints into core at the end of January 2016. Between now and then we have at least 74 issues to wade through. Beta 9 includes 32 merged pull requests.

In the interest of feeling confident about the code we’re committing to core, we are and will be making breaking changes in the Betas. Significantly, Beta 10 will remove the core directory, and will be incompatible with WordPress 4.3.

Short answer: you’re welcome to use the Betas in production if you understand the ramifications. When updating, we expect you to read through the changelog and thoroughly test each release with your project. You should probably have test coverage on any custom endpoints you’re writing. And, set aside time to properly debug any issues you uncover and submit pull requests with test coverage.

If you aren’t comfortable with aforementioned ramifications, please refrain from using the v2.0 Betas in production. We do encourage everyone to use them locally, or in staging / test environments, and look forward to your feedback.

Changelog

Here are some highlights:

  • Move tags and categories to top-level endpoints. Tags are now accessible at `/wp/v2/tags`, and categories accessible at `/wp/v2/categories`. Post terms reside at `/wp/v2/posts//tags` and `/wp/v2//categories`.
  • Return object for requests to `/wp/v2/taxonomies`. This is consistent with `/wp/v2/types` and `/wp/v2/statuses`.
  • Remove `rest_get_timezone()`. `json_get_timezone()` was only ever used in v1. This function causes fatals, and shouldn’t be used.
  • Rename `register_api_field()` to `register_rest_field()`. Introduces a `register_api_field()` function for backwards compat, which calls `_doing_it_wrong()`. However, `register_api_field()` won’t ever be committed to WordPress core, so you should update your function calls.
  • Change taxonomies’ `post_type` argument to `type`. It’s consistent with how we’re exposing post types in the API.
  • Sync infrastructure with shipped in WordPress 4.4.
    • `wp-includes/rest-api/rest-functions.php` is removed, and its functions moved into `wp-includes/rest-api.php`.
    • Send nocache headers for REST requests.
    • Fix handling of HEAD requests.
    • Mark `WP_REST_Server::get_raw_data()` as static.
    • Unabbreviate error string.
  • Change terms endpoints to use `term_id` not `tt_id`.
  • Standardize declaration of `context` param for `GET` requests across controllers. However, we’re still inconsistent in which controllers expose which params. Follow #1845 for further discussion.
  • Link types / taxonomies to their collections, and vice versa. Collections link to their type / taxonomy with the `about` relation; types / taxonomies link to their collection with the `item` relation, which is imperfect and may change in the future.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api