When working with the Wordpress REST API we can create our own endpoints and configure them according to our needs; one important feature of any API are URL parameters because they enable HTTP requests to include additional information. Let's analyze how to add those parameters to a given API endpoint.
The rest_api_init action hook
Each time we want to add custom endpoint we have to implement the rest_api_init action hook as shown below:
function rch_handle_params_request(){
//call to register_rest_route() will be here...
}
add_action("rest_api_init","rch_handle_params_request");
The register_rest_route function
This function is required to configure an endpoint from scratch and as you can see it uses several parameters:
register_rest_route(
"customAPI/v1",
"/post/(?P<id>\d+)",
array(
"methods" => "GET",
"callback" => "rch_get_custom_post"
)
);
The parameters are explained next:
- customAPI/v1 is the namespace or a way to group endpoints; it's like a prefix and must be unique throughout the API.
- /post/(?P\d+) is the URL parameter configuration; note how a regular expression is used to check the format of the id number.
- The HTTP method is set to GET which enables the route to have support for GET requests only.
- The callback parameter is set to a reference to the function which handles the HTTP request and generates the reponse.
Breaking down the callback function
The next code snippet must be placed outside the rch_handle_params_request function declaration:
function rch_get_custom_post($request){
$posts = get_posts(array(
"numberposts" => -1,
"post_type" => "post",
"post_status" => "publish",
"p" => $request['id']
));
if(!$posts){
return rest_ensure_response(new WP_Error(
"rest_not_found",
"The post does not exist",
array(
"status" => 404
)
));
}else{
return rest_ensure_response($posts);
}
}
I'm gonna try to sum up all the previous code so that you can understand it faster.
The get_posts function retrieves publications from Wordpress; two parameters are not very obvious; the first one is numberposts => -1 which indicates that all the posts matching the criteria must be retrieved and "p" => $request['id'] indicates that the id number of the matching publication must be equal to the property id of the request object; this property contains the value passed in via the URL parameter.
The if-block checks whether the $posts array is empty or not; when the $posts array is empty then an error object is retured otherwise the matching publication is returned.