How to Create a Custom Endpoint for the REST API (In 4 Steps)

Here, we’re inheriting information from the parent theme’s style sheet. Now that you have the basic elements in place, navigate to Appearance > Themes in your WordPress dashboard:

Your child theme should be visible in the dashboard. Give the Activate button a click, and your new theme is now ready to use.

2. Define Your Route

In this section, we’re going to create a new route that will enable us to retrieve the latest posts by category ID. We’ll use the following URL: 

http://localhost/wp-json/twentytwentyone-child/v1/latest-posts/

Remember to modify this URL to point at your own domain or local site. You’ll also need to replace with the actual category that you want to query. For example, here we’re retrieving all of the posts for category “1”:

http://localhost/wp-json/twentytwentyone-child/v1/latest-posts/1

If you’re unsure about a category’s ID, you can check this value in the WordPress dashboard. Navigate to Posts > Categories and you’ll see a list: 

You can now hover over the category that you want to query, and open it for editing. You’ll find the category ID in the URL. In the following screenshot, the category ID is “1”:

You can now add this category ID to your endpoint. At this point, if you enter the completed URL into your web browser, you’ll encounter an error message: 

This is because we haven’t defined this route yet. In FileZilla, open your theme’s functions.php file and add the following:

add_action('rest_api_init', function () {   register_rest_route( 'twentytwentyone-child/v1', 'latest-posts/(?Pd+)',array(                 'methods'  => 'GET',                 'callback' => 'get_latest_posts_by_category'       )); });

You can now save your changes and exit this file. In your browser, try reloading the URL. Your browser should respond with a 500 error:

Since we’ve defined this route, WordPress now recognizes it. However, we still need to specify the get_latest_posts_by_category() function as our callback, so let’s do that now.

3. Implement the Callback Function for Your Custom REST Endpoint

Our next task is implementing the callback function, which we’ll use to process and handle our GET request. Inside your functions.php file, start by retrieving the category_id argument from the $request parameter:

function get_latest_posts_by_category($request) {

Next, we need to create an $args array with the category key set to the value of category_id. This ID will be extracted from the route:

    $args = array(             'category' => $request['category_id']     );

Then, query for posts with the specified category ID. You can achieve this by calling the get_posts() method:

    $posts = get_posts($args);

If the array is empty, then we’ll display an error message that contains the empy_category code, plus a 404 status code. You can customize this based on your requirements. We’ll pass all of this information to the constructor of the WP_Error class: 

    if (empty($posts)) {     return new WP_Error( 'empty_category', 'There are no posts to display', array('status' => 404) );

After completing this setup, it’s time to create a new instance of the WP_REST_Response class. We can then pass in the $posts array, and return the REST response. By using the WP_REST_Response and WP_Error classes, we can ensure that our endpoint returns a valid JSON response: 

    $response = new WP_REST_Response($posts);     $response->set_status(200);      return $response; }

If you’ve been following along, then your completed code should look something like this:

function get_latest_posts_by_category($request) {      $args = array(             'category' => $request['category_id']     );      $posts = get_posts($args);     if (empty($posts)) {     return new WP_Error( 'empty_category', 'There are no posts to display', array('status' => 404) );      }      $response = new WP_REST_Response($posts);     $response->set_status(200);      return $response; } 

After adding this code to functions.php, save and close the file. Now, the only thing left is to put your custom endpoint to the test. 

4. Test Your Endpoint

In your browser tab, try visiting the URL we defined in the previous step. Make sure you replace with any valid category ID that’s registered with your WordPress website, for example: http://localhost/wp-json/twentytwentyone-child/v1/latest-posts/1:

You should now see a list of all the posts belonging to this category. It’s also worth entering a category ID that isn’t registered with your website. If your custom endpoint is working correctly, the browser should display the error message you defined in your functions.php file: 

This is all you need to create a simple custom endpoint for the REST API. If you want to continue developing this project, then we recommend providing sanitization and validation callbacks in addition to your main callback. This can help protect your site against code injections, including Cross-Site Scripting (XSS) attacks. 

To further protect your site and data, we recommend restricting access to your custom endpoint. You can achieve this by using the permission_callback() function.

Conclusion 

The Representational State Transfer (REST) Application Programming Interface (API) was a game-changer for the WordPress community. However, even this powerful API has its limits, and it’s possible that REST may not meet your exact needs.

If you’re struggling with this API’s limitations, you can create a custom endpoint in four easy steps: 

1. Create a child theme.
2. Define your route. 
3. Implement the callback function for your custom REST endpoint.
4. Test your endpoint. 

Do you have any questions about how to create a custom endpoint for the REST API? Let us know in the comments section below!