WordPress REST API for building and consuming HTTP-based JSON endpoints.

Since: 4.4.0
Source: wp-includes/rest-api.php, wp-includes/rest-api/

Components

Request Flow

HTTP Request
    └── rest_api_loaded()
            └── WP_REST_Server::serve_request()
                    ├── check_authentication()
                    ├── dispatch()
                    │       ├── rest_pre_dispatch filter
                    │       ├── match_request_to_handler()
                    │       ├── has_valid_params()
                    │       ├── sanitize_params()
                    │       └── respond_to_request()
                    │               ├── rest_request_before_callbacks
                    │               ├── permission_callback
                    │               ├── callback
                    │               └── rest_request_after_callbacks
                    ├── rest_post_dispatch filter
                    └── response_to_data()

Route Registration

add_action( 'rest_api_init', function() {
    register_rest_route( 'my-plugin/v1', '/items', array(
        'methods'             => WP_REST_Server::READABLE,
        'callback'            => 'my_plugin_get_items',
        'permission_callback' => '__return_true',
        'args'                => array(
            'per_page' => array(
                'type'    => 'integer',
                'default' => 10,
            ),
        ),
    ) );
} );

Constants

URL Structure

Default prefix: /wp-json/

/wp-json/                          → Site index
/wp-json/wp/v2/                    → Core namespace index
/wp-json/wp/v2/posts               → Posts collection
/wp-json/wp/v2/posts/123           → Single post
/wp-json/my-plugin/v1/items        → Custom route

Authentication

Authentication flows through the rest_authentication_errors filter:

add_filter( 'rest_authentication_errors', function( $result ) {
    if ( ! empty( $result ) ) {
        return $result; // Another auth already handled
    }
    
    if ( ! is_user_logged_in() ) {
        return new WP_Error( 'rest_not_logged_in', 'Not authenticated', array( 'status' => 401 ) );
    }
    
    return true;
} );

Built-in methods:

• Cookie + nonce (via X-WP-Nonce header)
• Application passwords (HTTP Basic auth)

Response Formats

Standard response with _links:

{
    "id": 123,
    "title": { "rendered": "Hello World" },
    "_links": {
        "self": [{ "href": "/wp-json/wp/v2/posts/123" }],
        "author": [{ "href": "/wp-json/wp/v2/users/1", "embeddable": true }]
    }
}

With ?_embed:

{
    "id": 123,
    "_embedded": {
        "author": [{ "id": 1, "name": "admin" }]
    }
}

Batch Requests

POST to /wp-json/batch/v1 with requests array:

{
    "requests": [
        { "path": "/wp/v2/posts/1", "method": "PUT", "body": { "title": "New" } },
        { "path": "/wp/v2/posts/2", "method": "DELETE" }
    ]
}