Wordpress REST API - URL parameters

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.