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.