register_rest_route( string $route_namespace, string $route, array $args = array(), bool $override = false ): bool

User Contributed Notes

1. Skip to note 9 content

   alordiel 5 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 20You must log in to vote on the helpfulness of this note

   Since WP 5.5.0 there is a notice if your registration of REST API route is not including the `permission_callback`. You may get some notice in debug.log like the following one:

   PHP Notice: register_rest_route was called incorrectly. The REST API route definition for /foo is missing the required permission_callback argument. For REST API routes that are intended to be public, use __return_true as the permission callback.

   To solve this problem you will need to add the `permission_callback` in arguments like the example from the “Routes and Endpoints Handbook”: https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/#permissions-callback
2. Skip to note 10 content

   Lance Cleveland 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 17You must log in to vote on the helpfulness of this note

   Args is a named array that usually includes the keys ‘methods’ and ‘callback’.

   ‘method’ defines which HTTP methods are to be processed by the function defined by ‘callback’.

   ‘method’ can be a string of comma-separated HTTP methods or an array of strings of HTTP methods.

   A common practice is to use the WP_REST_Server constants to set the ‘method’.

   WP_REST_Server::READABLE = ‘GET’

   WP_REST_Server::EDITABLE = ‘POST, PUT, PATCH’

   WP_REST_Server::DELETABLE = ‘DELETE’

   WP_REST_Server::ALLMETHODS = ‘GET, POST, PUT, PATCH, DELETE’

   Example

   
// Get a list of locations.
// Method GET via wp-json/store-locator-plus//locations/
//
// Calls the get_locations method of the current class when the route is matched.
//
register_rest_route( 'my-plugin-slug/v2' , '/locations/', array(
'methods' => 'GET',
'callback' => array(
$this,
'get_locations'
)
) );


   • The CREATABLE constant was also added in same version 4.4.0. WP_REST_Server::CREATABLE = ‘POST’

     Brennan Goewert 3 years ago
3. Skip to note 11 content

   abellowins 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note

   //The Following registers an api route with multiple parameters. 
   add_action( 'rest_api_init', 'add_custom_users_api');
   
   function add_custom_users_api(){
       register_rest_route( 'mmw/v1', '/users/market=(?P<market>[a-zA-Z0-9-]+)/lat=(?P<lat>[a-z0-9 .\-]+)/long=(?P<long>[a-z0-9 .\-]+)', array(
           'methods' => 'GET',
           'callback' => 'get_custom_users_data',
       ));
   }

   Make sure that your regex expressions are fine. If the data does not match then the URL will return a 404.
   Some examples are:

   (?P[a-zA-Z0-9-]+) for slug (you can change slug for your custom name)
   (?P\d+) for id
   (?P[a-z0-9 .\-]+) for longitude or latitude

   //Customize the callback to your liking
   function get_custom_users_data($data){
       //get users by market
       $users = mmw_get_custom_users();
       foreach ($users as $key => $user) {
           $market = $user['Market'];
           $long = $user['long'];
           $lat = $user['lat'];
   
           if( intval($market) === intval(trim($data['market'])) ){
               $result[] = array(
                   'user_login' => $user->user_login,
                   'avatar_url' => get_avatar_url($user->ID),
                   'lat' => $lat,
                   'long' => $long
               );
           }
       }
       return $result;
   }

   Edited to remove an extra ) in one of the regexes. – DevHub Team

   • After version 5.5.0 permission callback is required. If you did not pass the permission callback in $args Then you can see the below error. register_rest_route was called incorrectly. The REST API route definition for $route is missing the required permission_callback argument. For REST API routes that are intended to be public, use __return_true as the permission callback. Please see Debugging in WordPress for more information. (This message was added in version 5.5.0.) Here I have shared the example for your reference:

     // Pass this action in your __construct of your class. add_action( 'rest_api_init', array( $this, 'action__rest_api_init' ) );  /**  * [action__rest_api_init description]  *  * @return {[type]} [description]  */ function action__rest_api_init() { 	register_rest_route( 		'licences', // $namespace  		'/removed', // $route 		array( 			'callback' =>  array( $this, 'api__removed' ), 			'permission_callback' => '__return_true', 		) 	); }  /**  * [api__removed description]  *  * @return {[type]} [description]  */ function api__removed() { 	// do you code }

     Note: – licences and /removed only use for example.

     Jagir Bahesh 5 years ago
4. Skip to note 12 content

   derhans 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note

   In case you are a friend of type hinting and are wondering what is being passed to your callback method, it’s a WP_REST_Request object. It might help you with autocompletion and discovering other methods provided.

   public function wpdocs_get_lineitems( WP_REST_Request $data ) {
   	$params = $data->get_url_params();
   	// etc.
   }
5. Skip to note 13 content

   Lance Cleveland 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note

   Args , the named array cited above, can also contain an optional ‘args’ array of its own.

   The second args array contains the default arguments, required arguments, validation callback, and sanitization callback that are in place for each argument passed in with the REST request. The key name of this array is the name of the parameter being passed.

   See http://v2.wp-api.org/extending/adding/ under the “Arguments” section for more information and examples.

   Example
   
<?php
add_action( 'rest_api_init', function () {
register_rest_route( 'myplugin/v1', '/author/(?P\d+)', array(
'methods' => 'GET',
'callback' => 'my_awesome_func',
'args' => array(
'id' => array(
'validate_callback' => function($param, $request, $key) {
return is_numeric( $param );
}
),
),
) );
} );

6. Skip to note 14 content

   Keramot UL Islam 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   1. You can not use / (slash) at the beginning or end of the namespace, for example: plugin_name/api/.
   2. permission_callback is required argument of register_rest_route.

   function plugin_name_create_route() {
           add_action( 'rest_api_init', function() {
               register_rest_route( 'plugin_name/api', '/token/', array(
                   'methods' => 'POST',
                   'callback' =>  'plugin_name_route_api',
                   ‘permission_callback' => function() { return ''; }
               ) );
           } );
    }

   1. Callback takes the request object as a parameter.
   2. You can set the response headers with WP_Error class.

   function plugin_name_route_api( \WP_REST_Request $req ) {
   	$token = get_option('bearer_token');
   	$headers = $req->get_headers();
   	$auth_token = $headers['authorization'][0];
   
   	if ( $token != $auth_token ) {
   		return new WP_Error( '401', esc_html__( 'Not Authorized', 'text_domain' ), array( 'status' => 401 ) );
   	}
   
   	return json_encode(["message" => "Authorized"]);
   }

   • Returning the empty string in the permission_callback is equivalent to granting access. Using '__return_true' is preferred if the intention is to make an API public.

     Roy Orbitson 2 years ago
7. Skip to note 15 content

   Mustafa Uysal 8 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

   for the non-namespaced routing, call WP_REST_Server::register_route directly.
   Example

   add_action( 'rest_api_init', function ( $server ) {
   	$server->register_route( 'foo', '/foo', array(
   		'methods'  => 'GET',
   		'callback' => function () {
   			return 'baz';
   		},
   	) );
   } );

   will register foo endpoint without namespace. You can access http://example.com/wp-json/foo
   As a reminder, please ensure before registering non-namespaced routes. They can be useful for backward compatibility only.
8. Skip to note 16 content

   Roy Orbitson 2 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

   The permission_callback should return one of false, null, or a WP_Error if access is to be disallowed. Anything else, including other “falsey” values, will grant access.