WordPress REST API (Version 2)

2.0 Beta 15.0 (October 07, 2016)

• Introduce support for Post Meta, Term Meta, User Meta, and Comment Meta in
  their parent endpoints.

  For your meta fields to be exposed in the REST API, you need to register
  them. WordPress includes a register_meta() function which is not usually
  required to get/set fields, but is required for API support.

  To register your field, simply call register_meta and set the show_in_rest
  flag to true. Note: register_meta must be called separately for each meta
  key.

  (props @rmccue, @danielbachhuber, @kjbenk, @duncanjbrown, #2765)

• Introduce Settings endpoint.

  Expose options to the REST API with the register_setting() function, by
  passing $args = array( 'show_in_rest' => true ). Note: WordPress 4.7 is
  required. See changeset [38635][https://core.trac.wordpress.org/changeset/38635].

  (props @joehoyle, @fjarrett, @danielbachhuber, @jonathanbardo,
  @greatislander, #2739)

• Attachments controller, change permissions check to match core.

  Check for the upload_files capability when creating an attachment.

  (props @nullvariable, @adamsilverstein, #2743)

• Add ?{taxonomy}_exclude= query parameter

  This mirrors our existing support for ?{taxonomy}= filtering in the posts
  controller (which allows querying for only records with are associated with
  any of the provided term IDs for the specified taxonomy) by adding an
  equivalent _exclude variant to list IDs of terms for which associated posts
  should NOT be returned.

  (props @kadamwhite, #2756)

• Use get_comment_type() when comparing updating comment status.

  Comments having a empty comment_type within WordPress bites us again.
  Fixes a bug where comments could not be updated because of bad comparison
  logic.

  (props @joehoyle, #2753)

2.0 Beta 13.0 (March 29, 2016)

• BREAKING CHANGE: Fix Content-Disposition header parsing.

  Allows regular form submissions from HTML forms, as well as properly formatted HTTP requests from clients. Note: this breaks backwards compatibility, as previously, the header parsing was completely wrong.

  (props @rmccue, #2239)

• BREAKING CHANGE: Use compact links for embedded responses if they are available.

  Introduces curies for sites running WordPress 4.5 or greater; no changes for those running WordPress 4.4.

  (props @joehoyle, #2412)

• JavaScript client updates:

  • Support lodash, plus older and newer underscore: add an alias for _.contains
  • Add args and options on the model/collection prototypes
  • Rework category/tag mixins to support new API structure
  • Add workaround for the null/empty values returned by the API when creating a new post * these values are not accepted for subsequent updates/saves, so explicitly excluding them. See https://github.com/WP-API/WP-API/pull/2393
  • Better handling of the (special) me endpoint
  • Schema parsing cleanup
  • Introduce wp.api.loadPromise so developers can ensure api load complete before using

  (props @adamsilverstein, #2403)

• Only adds alternate link header for publicly viewable CPTs.

  (props @bradyvercher, #2387)

• Adds roles param for GET /wp/v2/users.

  (props @BE-Webdesign, #2372)

• Declares password in user schema, but never displays it.

  (props @danielbachhuber, #2386)

• Permits edit context for requests which can edit the user.

  (props @danielbachhuber, #2383)

• Adds rest_pre_insert_{$taxonomy} filter for terms.

  (props @kjbenk, #2377)

• Supports taxonomy collection args on posts endpoint.

  (props @joehoyle, #2287)

• Removes post meta link from post response.

  (props @joehoyle, #2288)

• Registers description attribute when registering args from schema.

  (props @danielbachhuber, #2362)

• Uses $comment from the database with rest_insert_comment action.

  (props @danielbachhuber, #2349)

• Removes unnecessary global variables from users controller.

  (props @claudiosmweb, #2335)

• Ensures GET /wp/v2/categories with out of bounds offset doesn’t return results.

  (props @danielbachhuber, #2313)

• Adds top-level support for date queries on posts and comments.

  (props @BE-Webdesign, #2266, #2291)

• Respects show_avatars setting for comments.

  (props @BE-Webdesign, #2271)

• Uses cached get_the_terms() for terms-for-post for better performance.

  (props @rmccue, #2257)

• Ensures comments search is an empty string.

  (props @rmccue, #2256)

• If no title is provided in create attachment request or file metadata, falls back to filename.

  (props @danielbachhuber, #2254)

• Removes unused $img_url_basename variable in attachments controller.

  (props @danielbachhuber, #2250)

2.0 Beta 12.0 (February 9, 2016)

• BREAKING CHANGE: Removes meta endpoints from primary plugin.

  If your project depends on post meta endpoints, please install WP REST API Meta Endpoints. For the gory history of meta, read #1425 and linked issues. At this time, we recommend using register_rest_field() to expose meta (docs).

  (props @danielbachhuber, #2172)

• BREAKING CHANGE: Returns original resource when deleting PTCU.

  Now that all resources require the force param, we don’t need to wrap delete responses with the trash state.

  (props @danielbachhuber, #2163)

• BREAKING CHANGE: Uses roles rather than role in the Users controller.

  Building the REST API gives us the opportunity to standardize on roles, instead of having both roles and role.

  (props @joehoyle, #2177)

• BREAKING CHANGES: Moves to consistent use of context throughout controllers.

  Contexts limit the data present in the response. Here’s how to think of them: embed correlates with sidebar representation, view represents the primary public view, and edit is the data expected for an editor.

  (props @danielbachhuber, #2205, #2204, #2203, #2218, #2216, #2230, #2184, #2235)

• BREAKING CHANGE: Removes post_* query param support for GET /wp/v2/comments.

  The proper pattern is to use GET /wp/v2/posts to fetch the post IDs to limit the request to.

  (props @danielbachhuber, #2165)

• BREAKING CHANGE: Introduces rest_validate_request_arg()/rest_sanitize_request_arg().

  Dedicated functions means we can use them for validating / sanitizing query args too. Removes WP_REST_Controller::validate_schema_property() and WP_REST_Controller::sanitize_schema_property().

  (props @danielbachhuber, #2166, #2213)

• Requires minimum value of 1 for page param.

  (props @danielbachhuber, #2241)

• Introduces media_type and mime_type params for GET /wp/v2/media.

  (props @danielbachhuber, #2231)

• Uses the term cache for post data.

  (props @rmccue, #2234)

• Supports for querying comments where post=0.

  (props @danielbachhuber, #1865)

• Exposes taxonomy and post type capabilities in context=edit.

  (props @danielbachhuber, #2216)

• Errors early when user can’t GET types or taxonomies when context=edit.

  (props @danielbachhuber, #2218)

• Passes original $request context to prepare_items_query.

  (props @danielbachhuber, #2211)

• Adds parent and parent_exclude params to GET Comments.

  (props @danielbachhuber, #2206)

• Enforces minimum 1 and maximum 100 values for per_page parameter.

  (props @danielbachhuber, #2209)

• Adds author and author_exclude params to GET Posts and Comments.

  (props @danielbachhuber, #2200, #2200)

• Adds menu_order param for GET Pages; support menu_order orderby.

  (props @danielbachhuber, #2193)

• Only calls sanitize_text_field() when sanitizing type=string,format=email.

  (props @danielbachhuber, #2185)

• Validates GET /wp/v2/comments private query params.

  Returns an error when user doesn’t have permission to use them, instead of silently discarding.

  (props @danielbachhuber, #2178)

• Explicitly prevents uploading attachments to other attachments or revisions.

  (props @danielbachhuber, #2180)

• Permits user urls to be edited through the API.

  (props @danielbachhuber, #2182)

• Marks all Status, Type and Taxonomy fields as readonly.

  (props @danielbachhuber, #2181)

• Adds validation callbacks to collection query params.

  (props @danielbachhuber, #2170, #2171, #2176, #2174, #2175)

• Links taxonomy terms to the post type collections they support.

  (props @danielbachhuber, #2167)

• Returns error when making a GET request with invalid context.

  (props @danielbachhuber, #2169)

• Adds trash status to GET /wp/v2/statuses.

  (props @danielbachhuber, #2158)

• Indicates when fields have HTML in schema.

  (props @joehoyle, #2159)

• Permits viewing of User who has published any Public posts.

  (props @danielbachhuber, #2155)

• Respects show_avatars option when adding avatars to Users.

  (props @nullvariable, #2151)

• Controllers use $namespace and $rest_base class variables for easier subclassing.

  (props @danielbachhuber, #2119, #2130, #2131, #2132, #2133, #2134, #2139, #2141, #2142)

2.0 Beta 11.0 (January 25, 2016)

• BREAKING CHANGE: Moves Post->Term relations to the Post Resource

  Previously, a client would fetch a Post’s Tags with GET /wp/v2/posts/<id>/tags.

  In Beta 11, an array of term ids is included on the Post resource.

  The collection of terms for a Post can be fetched with GET /wp/v2/tags?post=<id>.

  The WP_REST_Posts_Terms_Controller class no longer exists.

  (props @joehoyle, #2063)

• BREAKING CHANGE: Adds latest JS client including a minified version.

  See pull request for a summarized changelog.

  (props @adamsilverstein, #1981)

• BREAKING CHANGE: Changes featured_image attribute on Posts to featured_media.

  While featuring other attachment types isn’t yet officially supported, this makes it easier for us to introduce the possibility in the future.

  (props @danielbachhuber, #2044)

• BREAKING CHANGE: Uses discrete schema title for categories and tags.

  If you’ve used register_rest_field( 'term' ), you’ll need to change 'term' to 'tag' and/or 'category'.

  (props @danielbachhuber, #2005)

• BREAKING CHANGE: Makes many filters dynamic based on the controller type.

  If you were using the rest_prepare_term filter, you’ll need to change it to rest_prepare_post_tag or rest_prepare_category.

  If you were using rest_post_query or rest_terms_query, you’ll need update your use to rest_page_query, etc.

  If you were using rest_post_trashable, rest_insert_post or rest_delete_post, they are now dynamic based on the post type slug.

  (props @danielbachhuber, #2008, #2010, #2057, #2058)

• Renames GET /wp/v2/comments user param to author to match resource attribute.

  Not a breaking change, because it didn’t work in the first place.

  (props @danielbachhuber, #2105)

• Adds support for GET /wp/v2/pages parent=1,2,3.

  (props @danielbachhuber, #2101)

• Persists image metadata title and caption when not present in the request.

  (props @danielbachhuber, #2079)

• Add parent_exclude param to GET /wp/v2/posts.

  (props @danielbachhuber, #2077)

• Adds slug param support for collections of Posts, Users, and Taxonomy Terms.

  (props @danielbachhuber, #2071, #2072, #2103)

• When a comment is already trashed, returns 410:rest_already_trashed.

  (props @danielbachhuber, #2069)

• Filter the responses by context after processing additional fields.

  (props @danielbachhuber, #2067)

• Adds offset param support for collections of Posts, Users, Comments, and Taxonomy Terms.

  (props @danielbachhuber, #2061, #2062, #2064, #2076)

• Adds rest_insert_{$taxonomy} and rest_delete_{$taxonomy} actions.

  (props @danielbachhuber, #2060)

• Provides more helpful error message/code on Post Create/Update fail.

  (props @danielbachhuber, #2053)

• Forces GET /wp/v2/media to be limited to 'status' => [ inherit, private, trash ]

  (props @danielbachhuber, #2026)

• Uses more correct error code for Comment::delete permission check.

  (props @danielbachhuber, #2054)

• Calls prepare_item_for_response() directly in create and update methods.

  This lets us pass the original request through, giving the method and its filter genuine context, and avoids an
  unnecessary call to get_item().

  (props @danielbachhuber, #2038, #2040, #2041, #2043, #2042)

• Moves permission check methods across controllers.

  Placing them above the method they’re supposed to check makes the code more readable.

  (props @danielbachhuber, #2030, #2029, #2034, #2036, #2037, #2035, #2039)

• Requires force argument for DELETE /wp/v2/<taxonomy>/<id>.

  (props @danielbachhuber, #2028)

• Conditionally requires and defines REST API classes and functions.

  (props @danielbachhuber, #2023, #2024)

• Avoid a duplicate query for the comment count.

  (props @rmccue, #2015)

• Parses $date if available in prepare_date_response()

  (props @adamsilverstein, #1951)

• Abstracts POST /wp/v2/media permissions check.

  (props @danielbachhuber, #2003)

• Adds exclude param to getting collections of Posts, Users, Comments, and Taxonomy Terms.

  (props @danielbachhuber, #1998, #1999, #2000, #2002)

• Adds rest_comment_query for filtering GET /wp/v2/comments.

  (props @danielbachhuber, #2007)

• Uses HTTP status code 500 for db_update_error when creating an attachment.

  (props @danielbachhuber, #1993)

• Adds helpful description to force param across all DELETE registrations

  (props @danielbachhuber, #2004, #2027)

• In GET /wp/v2/<taxonomy>, drops support for orderby=>term_id.

  Only one id is exposed through the REST API.

  (props @danielbachhuber, #1990)

2.0 Beta 10.0 (January 11, 2016)

• SECURITY: Ensure media of private posts are private too.

  Reported by @danielbachhuber on 2016-01-08.

• BREAKING CHANGE: Removes compatibility repo for WordPress 4.3.

  WordPress 4.4 is now the minimum supported WordPress version.

  (props @danielbachhuber, #1848)

• BREAKING CHANGE: Changes link relation for types and taxonomies.

  In Beta 9, this link relation was introduced as item, which isn’t correct. The relation has been changed to https://api.w.org/items.

  (props @danielbachhuber, #1853)

• BREAKING CHANGE: Introduces edit context for wp/v2/types and wp/v2/taxonomies.

  Some fields have moved into this context, which require edit_posts and manage_terms, respectively.

  (props @danielbachhuber, #1894, #1864)

• BREAKING CHANGE: Removes post_format as a term _link for Posts.

  Post formats aren’t a custom taxonomy in the eyes of the REST API.

  (props @danielbachhuber, #1854)

• Declares parent query param for Pages.

  (props @danielbachhuber, #1975)

• Permits logged-in users to query for media.

  (props @danielbachhuber, #1973)

• Removes duplicated query params from Terms controller.

  (props @danielbachhuber, #1963)

• Adds include param to /wp/v2/posts, /wp/v2/users, /wp/v2/<taxonomy> and /wp/v2/comments.

  (props @danielbachhuber, #1961, #1964, #1968, #1971)

• Ensures GET /wp/v2/posts respects order and orderby params.

  (props @danielbachhuber, #1962)

• Fixes fatal by loading wp-admin/includes/user.php to expose wp_delete_user().

  (props @danielbachhuber, #1958)

• Permits making a post sticky when also supplying an empty password.

  (props @westonruter, #1949)

• Uses WP_REST_Request internally across controllers.

  (props @danielbachhuber, #1933, #1939, #1934, #1938)

• Cleans up permissions checks in WP_REST_Terms_Controller.

  (props @danielbachhuber, #1941)

• Uses show_in_rest to determine publicness for post types.

  (props @danielbachhuber, #1942)

• Makes description strings available for translation.

  (props @danielbachhuber, #1944)

• Checks assign_terms cap for taxonomy when managing post terms.

  (props @danielbachhuber, #1940)

• Defer to edit_posts of the custom post type when accessing private query vars.

  (props @danielbachhuber, #1886)

• Allows Terms collection params to be filtered.

  (props @rachelbaker, #1882)

• Renames post terms create/delete permissions callback.

  (props @wpsmith, #1923)

• Fixes invalid use of ‘uri’ as schema type.

  (props @wpsmith, #1913)

• Casts integer with (int) over intval for speed.

  (props @wpsmith, #1907)

• Fixes PHP Doc typo for validate_schema_property and sanitize_schema_property.

  (props @wpsmith, @danielbachhuber, #1909, #1910)

• Adds a helpful description to the filter argument.

  (props @danielbachhuber, #1885)

• Changes order of Users response to match schema order.

  (props @rachelbaker, #1879)

• Adjusts Posts pagination headers for filter params.

  (props @rachelbaker, #1878)

• Uses proper status code when failing to get comments of private post.

  (props @danielbachhuber, #1866)

• Fixes invalid capability for comments get items permissions callback.

  manage_comments doesn’t exist; moderate_comments does.

  (props @danielbachhuber, #1866)

• Permits creating comments without an assigned post.

  (props @danielbachhuber, #1857)

• Prevents error notice when show_in_rest isn’t set for a post type.

  (props @danielbachhuber, #1852)

2.0 Beta 9.0 (December 11, 2015)

• BREAKING CHANGE: 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/<id>/tags and /wp/v2/<id>/categories.

  (props @danielbachhuber, #1802)

• BREAKING CHANGE: Return object for requests to /wp/v2/taxonomies.

  This is consistent with /wp/v2/types and /wp/v2/statuses.

  (props @danielbachhuber, #1825)

• BREAKING CHANGE: Remove rest_get_timezone().

  json_get_timezone() was only ever used in v1. This function causes fatals, and shouldn’t be used.

  (props @danielbachhuber, #1823)

• BREAKING CHANGE: 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.

  (props @danielbachhuber, #1824)

• BREAKING CHANGE: Change taxonomies’ post_type argument to type.

  It’s consistent with how we’re exposing post types in the API.

  (props @danielbachhuber, #1824)

• 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. #34832
  • Fix handling of HEAD requests. #34837
  • Mark WP_REST_Server::get_raw_data() as static. #34768
  • Unabbreviate error string. #34818

• Change terms endpoints to use term_id not tt_id.

  (props @joehoyle, #1837)

• 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.

  (props @danielbachhuber, #1795, #1835, #1838)

• Link types / taxonomies to their collections, and vice versa.

  Collections link to their type / taxonomy with the about relation; types / taxonomies link to their colletion with the item relation, which is imperfect and may change in the future.

  (props @danielbachhuber, #1814, #1817, #1829. #1846)

• Add missing ‘wp/v2’ in Location Response header when creating new Post Meta.

  (props @johanmynhardt, #1790)

• Expose Post collection query params, including author, order, orderby and status.

  (props @danielbachhuber, #1793)

• Ignore sticky posts by default.

  (props @danielbachhuber, #1801)

• Include full image size in attachment sizes attribute.

  (props @danielbachhuber, #1806)

• In text strings, use id instead of ID.

  ID is an implementation artifact. Our Resources use id.

  (props @danielbachhuber, #1803)

• Ensure attachment.sizes[] use mime_type instead of mime-type.

  (props @danielbachhuber, #1809)

• Introduce rest_authorization_required_code().

  Many controllers returned incorrect HTTP codes, which this also fixes.

  (props @danielbachhuber, #1808)

• Respect core’s comment_registration setting.

  If it’s enabled, require users to be logged in to comment.

  (props @danielbachhuber, #1826)

• Default to wildcard when searching users.

  (props @danielbachhuber, #1827)

• Bring the wp-api.js library up to date for v2 of the REST API.

  (props @adamsilverstein, #1828)

• Add rest_prepare_status filter.

  (props @danielbachhuber, #1830)

• Make prepare_* filters more consistent.

  (props @danielbachhuber, #1831)

• Add rest_prepare_post_type filter for post types.

  (props @danielbachhuber, #1833)