Make WordPress Core

Opened 4 years ago

Last modified 4 years ago

#52629 new defect (bug)

Introduce a better way to deprecate REST API parameters

Reported by: sergeybiryukov's profile SergeyBiryukov Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: REST API Keywords:
Focuses: Cc:

Description (last modified by SergeyBiryukov)

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 in WP_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.

Change History (2)

#1 @SergeyBiryukov
4 years ago

  • Description modified (diff)

#2 @TimothyBlynJacobs
4 years ago

  • Milestone changed from Awaiting Review to Future Release

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 the transform_callback if it exists, and then issue a deprecation warning of some kind.

Note: See TracTickets for help on using tickets.