How to register a new WordPress REST API route & endpoint

WordPress is a brilliant tool for creating a blog, but when you consider it as a framework, it can be used for so much more. Knowing how to use the built-in REST API can be a fantastic tool in your armoury for getting the most out the platform and extending it far beyond its base functionality.

This post details how to register a new WordPress REST API route and endpoint. Once the route is registered and the endpoint is created, you can do whatever you want with it.

The example below returns a link to a random post. The code will live quite happily in your WordPress theme’s functions.php file, or a plugin if you’re that way inclined.

// Register the route: /wp-json/corenominal/get_random_post
// See: https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/
function corenominal_random_post_register_route(){
    register_rest_route( 'corenominal', '/get_random_post', array(
        'methods' => 'GET',
        'callback' => 'corenominal_get_random_post',
        'show_in_index' => false,
        'permission_callback' => '__return_true',
    ));
}
add_action( 'rest_api_init', 'corenominal_random_post_register_route' );

// Get a random post
function corenominal_get_random_post(){
    // Get a random post from the db: https://developer.wordpress.org/reference/functions/get_posts/
    $post = get_posts('post_type=post&orderby=rand&numberposts=1');

    // Return the URL of the post
    return get_permalink($post[0]);
}

The above example is intentionally simple and the callback function corenominal_get_random_post() (line 14) does not use any parameters. The next step would be to introduce some parameters and adjust the response accordingly.

// Register the route: /wp-json/corenominal/get_random_post
// See: https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/
function corenominal_random_post_register_route(){
    register_rest_route( 'corenominal', '/get_random_post', array(
        'methods' => 'GET',
        'callback' => 'corenominal_get_random_post',
        'show_in_index' => false,
        'permission_callback' => '__return_true',
    ));
}
add_action( 'rest_api_init', 'corenominal_random_post_register_route' );

// Get a random post
function corenominal_get_random_post($request){
    // Params into array
    $params = $request->get_params();

    // Test 'return' param has been sent
    if(isset($params['return'])){
        // Get a random post from the db: https://developer.wordpress.org/reference/functions/get_posts/
        $post = get_posts('post_type=post&orderby=rand&numberposts=1');

        // Send response based on value of 'return' param
        switch ($params['return']) {
            case 'full':
                // Add permalink to post our object and return full post
                $post[0]->permalink = get_permalink($post[0]);
                return $post[0];
                break;
            
            default:
                // Just return the permalink
                return get_permalink($post[0]);
                break;
        }        
    }

    // Return error
    return array('error' => 'No "return" param supplied. Use return=full || return=permalink');
}

In the above example, the callback function takes the request argument (line 14) before storing any available parameters in the $params array (line 16). The “return” param is then tested for existence (line 19) and a switch statement (line 24) is used to modify the response.

Update: I’ve now posted How to set-up a GitHub webhook to WordPress REST API endpoint which details the REST API route registration in a bit more detail.

For more information about extending the REST API, see the REST API Handbook.