The following is a snapshot of some of the changes to the REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. in WordPress 5.7. For more details, see the full list of closed tickets.
Endpoint Changes
Posts Collection Tax Query Accepts include_children
Introduced in 50157, the REST API posts collection endpoints have been updated to allow a more complex syntax for specifying the tax_query used when querying posts. Each taxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies.’s query parameters can now both accept a list of term ids or an object with a terms property.
Hierarchical taxonomies support an include_children property alongside terms. By default it’s disabled, but if set to true the flag is enabled for the generated tax_query to enable searching for posts that have the given terms or terms that are children of the given terms.
import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';
const query = {
categories: {
terms: [ 3, 5, 7 ],
include_children: true,
},
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );
See #39494 for more details.
Support modified_before and modified_after Query Parameters
Introduced in 50024 the REST API posts collection endpoints now accept modified_before and modified_after query parameters to query posts based on the post modified date instead of the post published date.
import { addQueryArgs } from '@wordpress/url';
import apiFetch from '@wordpress/api-fetch';
const query = {
modified_after: '2020-12-01T00:00:00Z',
modified_before: '2020-12-31T23:59:59Z',
};
apiFetch( { path: addQueryArgs( '/wp/v2/posts', query ) } );
As a result of this change, the posts controller now uses a date_query with a separate clause for each date related query parameter instead of a single clause with the before and after flags set.
See #50617 for more details.
Multiple Meta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. Values for a Key Can Be Deleted by Sending an Empty Array
Previously, to remove all values for a specific meta key, passing null as the value for that meta key was required. After 49966 an empty array can be passed instead.
register_post_meta( 'post', 'my_meta_key', array(
'type' => 'string',
'show_in_rest' => true,
) );
import apiFetch from '@wordpress/api-fetch';
const data = {
meta: {
my_meta_key: [],
}
};
apiFetch( { data, method: 'PUT', path: '/wp/v2/posts/1' } );
See #50790 for more details.
All Themes are Returned via the Themes Controller
As of 49925, the themes endpoint now returns all themes installed on the site, not just the active theme. By default, the endpoint returns both active and inactive themes, but the status query parameter can be used to limit the list to themes with the desired status.
Note, the theme_supports value is only exposed for the active theme. The field is omitted for inactive themes since declaring the supported theme features requires calls to add_theme_support which can only be done if the theme is active.
When querying solely for active themes, the only permission required is to be able to edit posts of any show_in_rest post type. However when querying for inactive themes the switch_themes or manage_network_themes capability is required.
In addition to the changes to the collection endpoint, a new single theme endpoint is available. For example, /wp/v2/themes/twentytwentyone will return information about Twenty Twenty One. For convenience, a link is also added to the currently active theme in the REST API Index if the current user has the requisite permissions. This is the recommended way for applications to discover the currently active theme.
{
"name": "WordPress Develop",
"_links": {
"help": [
{
"href": "http://v2.wp-api.org/"
}
],
"wp:active-theme": [
{
"href": "https://wordpress.test/wp-json/wp/v2/themes/twentytwentyone"
}
],
"curies": [
{
"name": "wp",
"href": "https://api.w.org/{rel}",
"templated": true
}
]
}
}
Lastly, the page, per_page, search and context query parameters are no longer exposed in the index as they are not supported by this endpoint.
See #50152 for more details.
Image Editor Accepts a List of Modifiers
The /wp/v2/media/<id>/edit endpoint introduced in WordPress 5.5 came with a limited API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. that accepted top-level rotation and crop declarations. In 50124 this API was made more powerful and flexible by accepting an array of modifications in the new modifiers request parameter.
import apiFetch from '@wordpress/api-fetch';
const data = {
modifiers: [
{
type: 'crop',
args: {
left : 0,
top : 0,
width : 80,
height: 80
}
},
{
type: 'rotate',
args: {
angle: 90
}
}
]
};
apiFetch( { data, method: 'POST', path: '/wp/v2/media/5/edit' } );
The previous query parameters have been marked as deprecated, but will continue to function as normal and do not currently issue deprecation warnings. Clients are encouraged to switch to the new syntax.
To alleviate server resources, whenever possible, clients should simplify redundant modifications before sending the request.
See #52192 for more details.
Parameter Validation
Non-String Enums
In 50010 support for type coercion was added to the enum JSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. Schema keyword. Previously, the enum keyword was validated by perform a strict equality check. For string types this is generally ok, but it prevented using alternative types like number when rich type support isn’t available.
Now the same level of type coercion/sanitization is applied when validating enum as all other validation checks. This means that a value of "1" will be accepted for an enum of [ 0, 1 ]. Additionally, object types now properly ignore key order when checking for equality.
See #51911 for more details.
Validation Error Codes
As of 50007, the rest_validate_value_from_schema function now returns specific error codes for each validation failure instead of the generic rest_invalid_param. For instance, if more array items are given than allowed by maxItems, the rest_too_many_itemserror code will be returned.
See #52317 for more details.
Return Detailed Error Information from Request Validation
Previously when a parameter failed validation only the first error message specified in the WP_Error instance was returned to the user. Since 50150 the REST API will now return detailed error information as part of the details error data key.
{
"code": "rest_invalid_param",
"message": "Invalid parameter(s): enum_a, enum_b",
"data": {
"status": 400,
"params": {
"enum_a": "enum_a is not one of a, b, c.",
"enum_b": "enum_b is not one of d, e, f."
},
"details": {
"enum_a": {
"code": "rest_not_in_enum",
"message": "enum_a is not one of a, b, c.",
"data": {
"enum": ["a", "b", "c"]
}
},
"enum_b": {
"code": "rest_not_in_enum",
"message": "enum_b is not one of d, e, f.",
"data": {
"enum": ["d", "e", "f"]
}
}
}
}
}
See #50617 for more details.
Application Passwords
Fine Grained Capabilities
When the Application Passwords REST API controllers were introduced, the edit_user meta capability was used for all permission checks. As of 50114, the REST API now uses specific meta capabilities for each action type.
create_app_passwordlist_app_passwordsread_app_passwordedit_app_passworddelete_app_passworddelete_app_passwords
By default, these capabilities all map to edit_user however they can now be customized by using the map_meta_cap filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..
See #51703 for more details.
Introspection Endpoint
50065 introduces a new Application Passwords endpoint for introspecting the app password being currently used for authentication. This endpoint is accessible via /wp/v2/users/me/application-passwords/introspect and will return the same information as the other endpoints. This allows for an application to disambiguate between multiple installations of their application which would all share the same app_id.
Clients can use this information to provide UI User interface hints about how the user is authenticated, for instance by displaying the App Passwords’s label. Or when their application is uninstalled by the user, they can automatically clean up after themselves by deleting their App Password.
See #52275 for more details.
Unique Application Names
As of 50030 the Application Passwords API enforces that each App Password has a unique name that cannot consist solely of whitespace characters. Additionally, invalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. characters are stripped from the provided application name.
See #51941 for more details.
Props to @flixos90, @desrosj for proofreading.
#5-7, #dev-notes, #rest-api
