WordPress REST API – custom routes & endpoints

Woocoders
Woocoders
13th March 2024
The WordPress REST API has revolutionized how developers interact with WordPress sites, offering a robust set of endpoints for managing content and performing various operations. While the API comes with a predefined set of routes for core functionalities, developers often need to create custom routes and endpoints to extend WordPress’ capabilities and meet specific project requirements. In this article, we’ll explore how to create custom routes and endpoints in the WordPress REST API.

Understanding Custom Routes and Endpoints

Routes in the WordPress REST API are URLs that correspond to specific resources or actions. Endpoints, on the other hand, are specific URLs within those routes that handle requests for data or perform actions. Custom routes and endpoints allow developers to:
  1. Extend Functionality: Add new features or functionalities to WordPress sites.
  2. Improve Performance: Optimize data retrieval and processing for specific use cases.
  3. Integrate Third-Party Services: Communicate with external services or APIs.
  4. Enhance Security: Implement additional security measures or restrictions.

Creating Custom Routes and Endpoints

To create custom routes and endpoints, you’ll need to use the register_rest_route function, which allows you to define new routes and specify the callback functions that handle requests to those routes. Here’s a basic example of how to create a custom route:
				
					// Register a custom route
function custom_route_init() {
    register_rest_route( 'myplugin/v1', '/custom-route/', array(
        'methods'  => 'GET',
        'callback' => 'custom_route_callback',
        'permission_callback' => '__return_true'
    ) );
}

// Callback function for the custom route
function custom_route_callback( $request ) {
    // Process request and return data
    $response = array(
        'message' => 'Hello, World!',
    );

    return rest_ensure_response( $response );
}

// Hook the custom route initialization
add_action( 'rest_api_init', 'custom_route_init' );

				
			

In this example, we register a custom route /myplugin/v1/custom-route/ that responds to GET requests with a simple message. The custom_route_callback function processes the request and returns the response.

Handling Request Parameters

Custom routes often require handling request parameters, such as query parameters or data sent in the request body. You can access these parameters using the $request object passed to your callback function. Here’s an example:

				
					// Callback function for a custom route with request parameters
function custom_route_with_params_callback( $request ) {
    $name = $request->get_param( 'name' );

    $response = array(
        'message' => 'Hello, ' . $name . '!',
    );

    return rest_ensure_response( $response );
}

				
			

Securing Custom Routes

When creating custom routes and endpoints, it’s essential to ensure they are secure and accessible only to authorized users. You can use WordPress’ authentication and permission systems to restrict access to specific routes. For example, to require authentication for a custom route, you can use the rest_authentication_errors filter:

				
					// Restrict access to a custom route to authenticated users
function restrict_custom_route_to_authenticated_users( $result ) {
    if ( ! is_user_logged_in() ) {
        return new WP_Error( 'rest_not_logged_in', 'You are not logged in.', array( 'status' => 401 ) );
    }

    return $result;
}

add_filter( 'rest_authentication_errors', 'restrict_custom_route_to_authenticated_users' );

				
			

Fetch the code with Javascript

To fetch the response for the custom route /myplugin/v1/custom-route/, you can use the fetch API in JavaScript. Here’s a basic example of how to fetch the response using a function:

				
					function fetchCustomRoute() {
    fetch('/wp-json/myplugin/v1/custom-route/')
        .then(response => {
            if (!response.ok) {
                throw new Error('Network response was not ok');
            }
            return response.json();
        })
        .then(data => {
            console.log(data);
            // Process the data as needed
        })
        .catch(error => {
            console.error('There was a problem with the fetch operation:', error);
        });
}

				
			
In this function, we use the fetch method to make a GET request to the custom route. We then check if the response is successful (response.ok), parse the JSON response using response.json(), and process the data in the second then block. If there’s an error, we catch it and log a message to the console.

Share this post: