Add filters to allow creating REST API middleware plugins

[jnylen0]

At WordPress.com we're working on v2 of our REST API which will be powered by WP-API. To make OAuth easier, and for historical reasons, we'll need to serve API requests for all our sites from public-api.wordpress.com.

We're testing some logic to make this work, but right now it is pretty fragile: we add a rest_endpoints filter, loop through all the endpoints, and wrap the endpoint callbacks with the logic to switch to the correct blog and then switch back afterwards.

It'd be much cleaner to have a pair of filters that are called immediately before and after endpoint callbacks. We can't use rest_pre_dispatch here because the request isn't matched to an endpoint when that filter is applied, and we're not really filtering the response, so rest_dispatch_request isn't appropriate either.

This will enable other middleware-style use cases where plugins need to perform validation or run logic before and/or after endpoint callbacks.

For cases where the new rest_request_after_callbacks filter is used to clean up after the before_callbacks filter, we need to ensure that it is always called, even if an error response will be sent. Therefore we need to meet the following conditions:

• If rest_request_before_callbacks is called, then we need to always call rest_request_after_callbacks as well.
• There cannot ever be any return statements in between these two filters (right now we are OK here).

Thanks to @mdawaffe and @joehoyle for working on and discussing this change with me.

[joehoyle]

FWIW when I was asked about this - I had presumed that rest_pre_dispatch was invoked after the correct endpoint had been matched, but that's not actually the case. I'm not totally sure why we did that, it seems like it would make sense to call rest_pre_dispatch just before the request is actually dispatched to the endpoint (right before), rather than before any endpoint has even been matched.

[jnylen0]

One difference is that as currently written, rest_pre_dispatch would allow a plugin to handle requests that don't match any defined endpoints. Not that that sounds like an especially good idea.

If we can move rest_pre_dispatch further down as you suggest, and add rest_post_dispatch, that would be a simpler way to meet our needs here.

[danielbachhuber]

Replying to jnylen0:

If we can move rest_pre_dispatch further down as you suggest, and add rest_post_dispatch, that would be a simpler way to meet our needs here.

I'm not sure I follow. rest_post_dispatch ​already exists?

Related #35628

[jnylen0]

True, ignore my comment :)

[danielbachhuber]

@rmccue @joehoyle @jnylen0 is this something we need to take action on at this point, or are we good?

[jnylen0]

We're using these filters heavily for our auth and multisite handling (switch to the right blog, validate tokens/cookies against the blog, restore the previous blog after the request, etc.)

There was some Slack discussion about the $did_run_before_callbacks in particular. This is there because if we call before_callbacks then we ​always need to call after_callbacks so that it can clean up (even if before_callbacks or the endpoint callbacks themselves error). But, if an earlier piece of logic returns an error (rest_authentication_errors, for example), then we don't need to call either one of these two new filters.

I've been meaning to add some tests but haven't had a chance yet.

Getting this patch merged would enable other plugins to do similar things with the API and allow us to run with one less core hack.

[kirasong]

Punting this to Future Release -- too late for 4.5 beta deadline.

[jnylen0]

Updated: simplified code and improved documentation.

Is it appropriate / desirable to have tests for the new filters? This patch is now quite simple, and the surrounding filters ( rest_pre_dispatch, rest_dispatch_request, rest_post_dispatch for example ) do not have tests.

[joehoyle]

In 38689:

REST API: Add filters to allow creating REST API middleware plugins.

Introduce two new filters: rest_request_before_callbacks and rest_request_after_callbacks to
assist REST API middleware plugins to perform pre-callback and cleanup hooks such as switch_to_blog()
or caching implementations.

Props jnylen0.
Fixes #35590.

[ocean90]

35590.2.diff​ improves the filter docs to make them more useful for ​https://developer.wordpress.org/reference/.

[ocean90]

In 38749:

Docs: Improve formatting of filter docs added in [38689].

Fixes #35590.