Full documentation about $args for register_rest_route?

Question

I'm currently setting up a WP REST API, and the tool is really impressive and the amount of possibilities vast. I would however really love it to have a full documentation listing all of the possible keys you can provide for $args when calling register_rest_route, just as you have it with register_post_type.

We're slowly building our own documentation with the gathered information across different pages since more than a week now, but wondered if there isn't a full documentation on this?

Answer 1

full documentation listing all of the possible keys you can provide for $args when calling register_rest_route, just as you have it with register_post_type

register_rest_route(), as of writing, doesn't have such a documentation; however, you can call $request->get_attributes() inside of your endpoint callback to get the full (registration) options (including those not explicitly specified) for that specific endpoint.

• Excerpt from https://developer.wordpress.org/rest-api/requests/#attributes:

  If we made a GET request to my-namespace/v1/books, and then we called $request->get_attributes() inside of our endpoint callback, we would be returned all of the registration options for the my-namespace/v1/books endpoint.

  In the attributes we will get a response containing supported methods, options, whether to show this endpoint in the index, a list of registered arguments for the endpoint, and our registered callbacks.

So for example, the following registers a route containing 2 endpoints:

add_action( 'rest_api_init', 'my_plugin_register_rest_routes' );
function my_plugin_register_rest_routes() {
    register_rest_route( 'my-plugin/v1', 'foo', array(
        // Endpoint 1 - Get an item.
        array(
            'callback'            => 'my_plugin_rest_get_foo',
            'permission_callback' => '__return_true',
        ),

        // Endpoint 2 - Create an item.
        array(
            'methods'             => 'POST',
            'callback'            => 'my_plugin_rest_create_foo',
            'permission_callback' => 'my_plugin_rest_create_foo_permissions_check',
            'args'                => my_plugin_rest_create_foo_arguments(),
            'show_in_index'       => false,
        ),
    ) );
}

function my_plugin_rest_get_foo( WP_REST_Request $request ) {
    return $request->get_attributes();
}

function my_plugin_rest_create_foo( WP_REST_Request $request ) {
    return array( $request->get_attributes(), $request->get_params() );
}

function my_plugin_rest_create_foo_permissions_check() {
    return current_user_can( 'manage_options' );
}

function my_plugin_rest_create_foo_arguments() {
    $args = array();

    $args['title'] = array(
        'type'              => 'string',
        'required'          => true,
        'sanitize_callback' => 'my_plugin_title_arg_sanitize_callback',
    );

    $args['color'] = array(
        'type'     => 'string',
        'required' => true,
        'enum'     => array( 'red', 'green', 'blue' ),
    );

    return $args;
}

function my_plugin_title_arg_sanitize_callback( $value, WP_REST_Request $request, $param ) {
    return wp_filter_kses( $value ); // allows basic HTML; e.g. <b> is OK, but not <hr />
}

And here's what the endpoint callback returned in my case (WordPress v6.0):

• GET my-plugin/v1/foo

  Request via cURL:
  curl -X GET https://example.com/wp-json/my-plugin/v1/foo
  
  Sample response:
  {
      "methods": {
          "GET": true
      },
      "accept_json": false,
      "accept_raw": false,
      "show_in_index": true,
      "args": [],
      "callback": "my_plugin_rest_get_foo",
      "permission_callback": "__return_true"
  }
  

• POST my-plugin/v1/foo

  Request via cURL:
  curl --user "<username>:<application password>"
      -X POST https://example.com/wp-json/my-plugin/v1/foo
      -H "Content-Type: application/json"
      -d '{"title": "test with <b>HTML</b><hr /> yeah", "color": "blue"}'
  
  Sample response:
  [{
      "methods": {
          "POST": true
      },
      "accept_json": false,
      "accept_raw": false,
      "show_in_index": false,
      "args": {
          "title": {
              "type": "string",
              "required": true,
              "sanitize_callback": "my_plugin_title_arg_sanitize_callback"
          },
          "color": {
              "type": "string",
              "required": true,
              "enum": ["red", "green", "blue"]
          }
      },
      "callback": "my_plugin_rest_create_foo",
      "permission_callback": "my_plugin_rest_create_foo_permissions_check"
  }, {
      "title": "test with <b>HTML<\/b> yeah",
      "color": "blue"
  }]
  

So as you could see, each endpoint contains 7 top-level attributes, namely:

• methods — One or more HTTP methods allowed for the endpoint.

• args — Arguments for the endpoint.

• callback — The main callback function for responding to the request.

• permission_callback — A function which checks if the user can perform the action (reading, updating, etc.) before the real/main callback is called.

  Note: As of WordPress v5.5, if a permission_callback is not provided, the REST API will issue a _doing_it_wrong notice. So at bare minimum, an endpoint should always have both callback and permission_callback. And for REST API routes that are intended to be public, you can use __return_true as the permission callback.

• show_in_index — A boolean indicating whether the endpoint should be included in the route index, e.g. at https://example.com/wp-json/my-plugin/v1 in my case.

  Note: You can omit your REST routes/endpoints from the index by using 'show_in_index' => false when registering your REST routes. However, the routes themselves will still be accessible. But you can use the permission callback to limit access to your endpoints.

• accept_json and accept_raw — In REST API v1, (I believe) they were WP_JSON_Server::ACCEPT_JSON and WP_JSON_Server::ACCEPT_RAW respectively.

  But in REST API v2, those "accept_xxx" are false by default, so I don't know what these are for in REST API v2. Maybe they're defined just for back-compat? 🤔

And as for the first four attributes above, they're well-documented in the REST API handbook:

• https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/
• https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/