register_rest_route

Registers a REST API route.

Description

register_rest_route( (string) $namespace, (string) $route, (array) $args = array(), (bool) $override = false ); 

Parameters (4)

0. $namespace (string)
The first URL segment after core prefix. Should be unique to your package/plugin.
1. $route (string)
The base URL for route you are adding.
2. $args — Optional. (array) => array()
Either an array of options for the endpoint, or an array of arrays for multiple methods. Default empty array.
3. $override — Optional. (bool) => false
If the route already exists, should we override it? True overrides, false merges (with newer overriding if duplicate keys exist). Default false.

Usage

  1. if ( !function_exists( 'register_rest_route' ) ) { 
  2. require_once ABSPATH . WPINC . '/rest-api.php'; 
  3.  
  4. // The first URL segment after core prefix. Should be unique to your package/plugin. 
  5. $namespace = ''; 
  6.  
  7. // The base URL for route you are adding. 
  8. $route = ''; 
  9.  
  10. // Optional. Either an array of options for the endpoint, or an array of arrays for 
  11. // multiple methods. Default empty array. 
  12. $args = array(); 
  13.  
  14. // Optional. If the route already exists, should we override it? True overrides, 
  15. // false merges (with newer overriding if duplicate keys exist). Default false. 
  16. $override = false; 
  17.  
  18. // NOTICE! Understand what this does before running. 
  19. $result = register_rest_route($namespace, $route, $args, $override); 
  20.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/rest-api.php  
  1. function register_rest_route( $namespace, $route, $args = array(), $override = false ) { 
  2. /** @var WP_REST_Server $wp_rest_server */ 
  3. global $wp_rest_server; 
  4.  
  5. if ( empty( $namespace ) ) { 
  6. /** 
  7. * Non-namespaced routes are not allowed, with the exception of the main 
  8. * and namespace indexes. If you really need to register a 
  9. * non-namespaced route, call `WP_REST_Server::register_route` directly. 
  10. */ 
  11. _doing_it_wrong( 'register_rest_route', __( 'Routes must be namespaced with plugin or theme name and version.' ), '4.4.0' ); 
  12. return false; 
  13. } else if ( empty( $route ) ) { 
  14. _doing_it_wrong( 'register_rest_route', __( 'Route must be specified.' ), '4.4.0' ); 
  15. return false; 
  16.  
  17. if ( isset( $args['args'] ) ) { 
  18. $common_args = $args['args']; 
  19. unset( $args['args'] ); 
  20. } else { 
  21. $common_args = array(); 
  22.  
  23. if ( isset( $args['callback'] ) ) { 
  24. // Upgrade a single set to multiple. 
  25. $args = array( $args ); 
  26.  
  27. $defaults = array( 
  28. 'methods' => 'GET',  
  29. 'callback' => null,  
  30. 'args' => array(),  
  31. ); 
  32. foreach ( $args as $key => &$arg_group ) { 
  33. if ( ! is_numeric( $key ) ) { 
  34. // Route option, skip here. 
  35. continue; 
  36.  
  37. $arg_group = array_merge( $defaults, $arg_group ); 
  38. $arg_group['args'] = array_merge( $common_args, $arg_group['args'] ); 
  39.  
  40. $full_route = '/' . trim( $namespace, '/' ) . '/' . trim( $route, '/' ); 
  41. $wp_rest_server->register_route( $namespace, $full_route, $args, $override ); 
  42. return true;