Opened 4 years ago
Last modified 4 years ago
#52629 new defect (bug)
Introduce a better way to deprecate REST API parameters
Reported by: |
|
Owned by: | |
---|---|---|---|
Milestone: | Future Release | Priority: | normal |
Severity: | normal | Version: | |
Component: | REST API | Keywords: | |
Focuses: | Cc: |
Description (last modified by )
Background: #52192.
[50124] introduced new endpoints to allow for batch image editing using the REST API, and soft-deprecated some older parameters. Splitting this out from #52192 to figure out a more formal way to deprecate them.
@SergeyBiryukov, comment:17:ticket:52192:
DEPRECATED: Use
modifiers
instead
Putting this in translatable descriptions doesn't seem to follow any other patterns in core. Is that necessary? Is there anything wrong with using the older format, apart from the newer one taking precedence?
If we want everyone to stop using the older format, could we call
_deprecated_argument()
instead when any of these older arguments are used? That would also allow us to specify the version in which they were deprecated.
At the very least,
modifiers
should be moved out of the translatable strings and replaced with a placeholder, to prevent it from being translated.
I think these changes would also benefit from
@since
tags on the affected methods.
@TimothyBlynJacobs, comment:19:ticket:52192:
AFAIK, we haven't deprecated any REST API parameters yet, this is the first. At a later point I plan on adding a more formal
deprecated
syntax that we could apply to the parameter schemas. So at the moment, this is just a soft deprecation.
The problem generally is that we don't have a good way to generate changelogs for the REST API. We could add
@since
markers, but they aren't picked up by the REST API reference documentation. We also haven't really done this in the past. AFAICT the only usages are inWP_REST_Posts_Controller::get_collection_params()
. Ideally, we'd make this available in the schema definition for each parameter.
Putting
Deprecated
in the parameter description means that it will be picked up by the REST API reference. Though for some reason, the edit endpoint isn't being picked up at all. I'll take a look at that when we regenerate our docs for 5.7.
My general thinking has been added something like this to a parameter definition.
[ 'deprecated' => [ 'version' => '5.7', 'message' => 'Use the new modifiers parameter', 'transform_callback' => function( $request ) { $request['modifiers'] = do_something_with_old_value( $request['crop'] ); } ] ];
Then the
WP_REST_Request
object would look for any parameters that have a deprecated flag, call thetransform_callback
if it exists, and then issue a deprecation warning of some kind.