Hello everyone. Remember us? Today, I can finally announce the release of version 1.2 of the WP REST API.

A short nine months after our last release we have support for Cross-Origin Resource Sharing, full request hijacking, JSON encode/decode errors, and a swarm of bug fixes.

Here are the expanded highlights:

• Add handling for Cross-Origin Resource Sharing (CORS) OPTIONS requests.

  Preflighted requests (using the OPTIONS method) include the headers Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Credentials in the response, if the HTTP origin is set.

  (props @rmccue, #281)

• Allow overriding full requests.

  The json_pre_dispatch filter allows a request to be hijacked before it is dispatched. Hijacked requests can be anything a normal endpoint can return.

  (props @rmccue, #281)

• Check for JSON encoding/decoding errors.

  Returns the last error (if any) occurred during the last JSON encoding or decoding operation.

  (props @joshkadis, @rmccue, #461)

• Add filtering to the terms collection endpoint.

  Available filter arguments are based on the get_terms() function. Example: /taxonomies/category/terms?filter[number]=10 would limit the response to 10 category terms.

  (props @mauteri, #401, #347)

• Add handling for the role parameter when creating or updating a user.

  Allow users to be created or updated with a provided role.

  (props @pippinsplugins, #392, #335)

• Add handling for the post_id parameter when creating media. Allow passing the post_id parameter to associate a new media item with a post.

  (props @pkevan, #294)

• Handle route matching for - in taxonomy and terms.

  Previously the regular expression used to match taxonomy and term names did not support names with dashes.

  (props @EdHurtig, @evansobkowicz, #410)

• Handle JSONP callback matching for . in the function name.

  Previously the regular expression used to match JSONP callback functions did not support names with periods.

  (props @codonnell822, #455)

• Fix the Content-Type header for JSONP requests.

  Previously JSONP requests sent the incorrect application/json Content-Type header with the response. This would result in an error if strict MIME checking was enabled. The Content-Type header was corrected to application/javascript for JSONP responses.

  (props @simonlampen, #380)

• Add $context parameter to json_prepare_term filter.

  Terms responses can now be modified based on the context parameter of the request.

  (props @traversal, #316)

• Move the JavaScript client library into the plugin.

  Previously, the wp-api.js file was a separate repository. The JavaScript client has moved back into the plugin to coordinate code changes.

  (props @tlovett1, #730)

• Always return an object for media sizesThe media sizes value should always be an object even when empty.

  Previously, if a media item did not have any sizes set, an empty array was returned.

  Compatibility warning: Clients should be prepared to accept an empty object as a value for media sizes.

  (props @maxcutler, #300)

• Give top-level posts a null parent value.

  For date type consistency, post parent property should be null. Previously, parent-less posts returned 0 for parent.

  Compatibility warning: Clients should be prepared to accept null as a value for post parent.

  (props @maxcutler, #391)

• Move permission checks out of WP_JSON_Posts.

  Introduce json_check_post_permission() function to allow post object capability checks to be used outside the WP_JSON_Posts class.

  Deprecation warning: Calling WP_JSON_Posts::check_read_permission and WP_JSON_Posts::check_edit_permission is now deprecated.

  (props @rachelbaker, #486, #378)

• Split comment endpoints into separate class.

  All comment handling has moved to the WP_JSON_Comments class.

  Deprecation warning: Calling WP_JSON_Posts::get_comments, WP_JSON_Posts::get_comment, WP_JSON_Posts::delete_comment, and WP_JSON_Posts::prepare_comment is now deprecated.

  (props @whyisjake, @rmccue, @rachelbaker, #378)

• Split meta endpoints into separate class.

  All post meta handling has moved to the new WP_JSON_Meta_Posts class.

  Deprecation warning: Calling WP_JSON_Posts::get_all_meta, WP_JSON_Posts::get_meta, WP_JSON_Posts::update_meta, WP_JSON_Posts::add_meta, WP_JSON_Posts::delete_meta, WP_JSON_Posts::prepare_meta, and WP_JSON_Posts::is_valid_meta_data is now deprecated.

  (props @rmccue, @rachelbaker, #358, #474)

• Rename internal create methods.

  Deprecation warning: Calling WP_JSON_Posts::new_post, WP_JSON_CustomPostType::new_post and WP_JSON_Posts::new_post is now deprecated.

  (props @rachelbaker, @rmccue, #374, #377, #376)

• Fix discrepancies in edit and create posts documentation examples.

  Corrected the edit and create posts code examples in the Getting Started section. The new post example was updated to include the required content_raw parameter. The new and edit posts examples were updated to use a correct date parameter.

  (props @rachelbaker, #305)

• Update the cookie authentication documentation examples.

  With 1.1 the localized JavaScript object for wp-api.js changed to WP_API_Settings. This updates the Authentication section documentation nonce example to use the updated object name.

  (props @rachelbaker, #321)

• Add flexibility and multisite support to unit tests.

  Tests can be run from any WordPress install, and are not limited to only as a plugin installed within a WordPress.org develop checkout. Unit tests are now run against a multisite installation.

  (props @danielbachhuber, #397)

As always, we’ve got a full list of all the changes and a longer changelog.

Here’s who contributed to this release:

$ git shortlog 1.1.1...1.2 --summary
    1  Chris O'Donnell
    12  Daniel Bachhuber
     1  David Hayes
     4  DrewAPicture
     7  Eddie Hurtig
     2  JDGrimes
     1  Japh
     5  Josh Kadis
     1  Josh Pollock
     1  Justin Sternberg
     2  K.Adam White
     1  Marko Heijnen
     2  Max Cutler
     2  Mike Auteri
     1  Milan Dinić
     1  NikV
     3  Paul Kevan
     2  Pippin Williamson
    86  Rachel Baker
    73  Ryan McCue
     7  Sarah Gooding
     1  Simon Lampen
     2  Taylor Lovett
     1  Travis Hensgen
     1  Wayne K. Walrath
     1  ironpaperweight
     1  kalenjohnson
     1  kellbot
     1  paul de wouters

Release Plan

1.2 will be the last major release on the 1.x branch of the plugin. We’ve been working hard over the past four months, with the aim of releasing a beta for version 2.0 next month.

For existing code written for version 1.x we will issue a final 1.x release as a compatibility shim to seamlessly connect existing code to version 2.

#json-api, #rest-api