As I’ve continued to work with integration mobile applications with the WordPress REST API, there have been a few instances in which I’ve wanted to inspect, manage, or manipulate incoming REST API Requests.
There’s a number of reasons you may want to manipulate incoming WordPress REST API requests before they actually begin interacting with the core application. In my case, I needed to determine:
- which endpoint is being requested,
- check whether or not a specific key is being bassed,
- return an error if not or proceed with further processing.
But that’s one of many different possibilities available. What I’m more interested in, at least in this article, is showing how to manipulate a request before it’s actually sent to be processed.
Incoming WordPress REST API Requests
About the Hook
Note the rest_pre_dispatch
hook is triggered before the REST API request is processed by WordPress. This hook allows us to intercept the incoming request and manipulate it in whatever way we need.
Sometimes, we may just want to inspect information that’s incoming. Other times, we may need to modify the request before sending through the rest of the lifecycle. Some of this manipulation could include:
- verifying parameters or headers,
- checking the user authentication,
- or performing some action and the data to be processed.
When referencing the documentation, you’ll see it requires three parameters:
$result
$server
$request
The $result
can different types of data returned to the client (it could be an array, a boolean, an integer, a string, an instance of WP_Error
, and so on). The $server
is an instance of WP_REST_Server
which is the primary class responsible for handling the request. And the $request
contains data from which we can pull information about the request.
A Practical Example
Say, for example, we want to do the following:
- read the route being processed,
- return if we’re not accessing the
users
endpoint, - read a specific header value,
- do some specialized processing,
- handle an error or return as usual.
Pulling from my own code, here’s an example of how I did the following (with some of the core domain logic omitted):
add_filter(
'rest_pre_dispatch',
function (mixed $result, WP_REST_Server $server, WP_REST_Request $request) {
// Get the route being requested
$route = $request->get_route();
// Only proceed if we're creating a user
if ( false === strpos($route, '/wp/v2/users')) {
return $result;
}
// Get the key from the request headers
$key = $request->get_header( 'X-Application-Key' );
// Handle specialized processing here...
// $value = ...
if (is_wp_error($value)) {
return new WP_Error(
'rest_cannot_create_object',
__( 'There was a problem creating the object.' ),
[
'status' => rest_authorization_required_code(),
'data' => $value
]
);
}
// Additional processing...
// Return data to the client to parse.
return ['success' => true];
}
After this processing is done, your application can then write conditional logic on whether to proceed with the request or to stop and handle the error or if the value returned is false
.
The Point of the Hook
Ultimately, the point is to know that you can manipulate a request before it’s processed by the REST API and this is the hook available that allows you to do so.