Class: WP_REST_Server

Core class used to implement the WordPress REST API server.


Properties

Name Type(s) Default Value Summary
namespaces array Namespaces registered to the server.
endpoints array Endpoints registered to the server.
route_options array Options defined for the routes.

Methods

WP_REST_Server:: __construct( )

Instantiates the REST server. Since 4.4.0.


WP_REST_Server:: check_authentication( )

Checks the authentication headers if supplied. Since 4.4.0.

Returns

WP_Error | null

WP_Error indicates unsuccessful login, null indicates successful or no authentication provided


WP_REST_Server:: dispatch( WP_REST_Request $request )

Matches the request to a callback and call it. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Request to attempt dispatching.

Returns

WP_REST_Response

Response returned by the callback.


Embeds the links from the data into the request. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$data array

Data from the request.

Returns

array

{ Data with sub-requests embedded.

@type array [$_links]    Links.
@type array [$_embedded] Embeddeds.

}


WP_REST_Server:: envelope_response( WP_REST_Response $response, boolean $embed )

Wraps the response in an envelope. Since 4.4.0.

The enveloping technique is used to work around browser/client compatibility issues. Essentially, it converts the full HTTP response to data instead.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response object.

$embed boolean

Whether links should be embedded.

Returns

WP_REST_Response

New response with wrapped data


WP_REST_Server:: error_to_response( WP_Error $error )

Converts an error to a response object. Since 4.4.0.

This iterates over all error codes and messages to change it into a flat array. This enables simpler client behaviour, as it is represented as a list in JSON rather than an object/map.

Arguments

Name Type(s) Default Value Description
$error WP_Error

WP_Error instance.

Returns

WP_REST_Response

List of associative arrays with code and message keys.


Retrieves the CURIEs (compact URIs) used for relations. Since 4.5.0.

Extracts the links from a response into a structured hash, suitable for direct output.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response to extract links from.

Returns

array

Map of link relation to list of link hashes.


WP_REST_Server:: get_data_for_route( string $route, array $callbacks, string $context = 'view' )

Retrieves publicly-visible data for the route. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$route string

Route to get data for.

$callbacks array

Callbacks to convert to data.

$context string

Optional. Context for the data. Accepts 'view' or 'help'. Default 'view'.

Returns

array | null

Data for the route, or null if no publicly-visible data.


WP_REST_Server:: get_data_for_routes( array $routes, string $context = 'view' )

Retrieves the publicly-visible data for routes. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$routes array

Routes to get data for.

$context string

Optional. Context for data. Accepts 'view' or 'help'. Default 'view'.

Returns

array

Route data to expose in indexes.


WP_REST_Server:: get_headers( array $server )

Extracts headers from a PHP-style $_SERVER array. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$server array

Associative array similar to $_SERVER.

Returns

array

Headers extracted from the input.


WP_REST_Server:: get_index( array $request )

Retrieves the site index. Since 4.4.0.

This endpoint describes the capabilities of the site.

Arguments

Name Type(s) Default Value Description
$request array

{ Request.

@type string $context Context.

}

Returns

array

Index entity


WP_REST_Server:: get_json_last_error( )

Returns if an error occurred during most recent JSON encode/decode. Since 4.4.0.

Strings to be translated will be in format like "Encoding error: Maximum stack depth exceeded".

Returns

boolean | string

Boolean false or string error message.


WP_REST_Server:: get_namespace_index( WP_REST_Request $request )

Retrieves the index for a namespace. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

REST request instance.

Returns

WP_REST_Response | WP_Error

WP_REST_Response instance if the index was found, WP_Error if the namespace isn't set.


WP_REST_Server:: get_namespaces( )

Retrieves namespaces registered on the server. Since 4.4.0.

Returns

array

List of registered namespaces.


WP_REST_Server:: get_raw_data( )

Retrieves the raw request entity (body). Since 4.4.0.

Returns

string

Raw request data.


Retrieves links from a response. Since 4.4.0.

Extracts the links from a response into a structured hash, suitable for direct output.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response to extract links from.

Returns

array

Map of link relation to list of link hashes.


WP_REST_Server:: get_route_options( string $route )

Retrieves specified options for a route. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$route string

Route pattern to fetch options for.

Returns

array | null

Data as an associative array if found, or null if not found.


WP_REST_Server:: get_routes( )

Retrieves the route map. Since 4.4.0.

The route map is an associative array with path regexes as the keys. The value is an indexed array with the callback function/method as the first item, and a bitmask of HTTP methods as the second item (see the class constants).

Each route can be mapped to more than one callback by using an array of the indexed arrays. This allows mapping e.g. GET requests to one callback and POST requests to another.

Note that the path regexes (array keys) must have @ escaped, as this is used as the delimiter with preg_match()

Returns

array

'/path/regex' => array( $callback, $bitmask ) or '/path/regex' => array( array( $callback, $bitmask ), ...).


WP_REST_Server:: json_error( string $code, string $message, integer $status = null )

Retrieves an appropriate error representation in JSON. Since 4.4.0.

Note: This should only be used in WP_REST_Server::serve_request(), as it cannot handle WP_Error internally. All callbacks and other internal methods should instead return a WP_Error with the data set to an array that includes a 'status' key, with the value being the HTTP status to send.

Arguments

Name Type(s) Default Value Description
$code string

WP_Error-style code.

$message string

Human-readable message.

$status integer

Optional. HTTP status code to send. Default null.

Returns

string

JSON representation of the error


WP_REST_Server:: register_route( string $namespace, string $route, array $route_args, boolean $override = false )

Registers a route to the server. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$namespace string

Namespace.

$route string

The REST route.

$route_args array

Route arguments.

$override boolean

Optional. Whether the route should be overridden if it already exists. Default false.


WP_REST_Server:: remove_header( string $key )

Removes an HTTP header from the current response. Since 4.8.0.

Arguments

Name Type(s) Default Value Description
$key string

Header key.


WP_REST_Server:: response_to_data( WP_REST_Response $response, boolean $embed )

Converts a response to data to send. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response object.

$embed boolean

Whether links should be embedded.

Returns

array

{ Data with sub-requests embedded.

@type array [$_links]    Links.
@type array [$_embedded] Embeddeds.

}


WP_REST_Server:: send_header( string $key, string $value )

Sends an HTTP header. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

Header key.

$value string

Header value.


WP_REST_Server:: send_headers( array $headers )

Sends multiple HTTP headers. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$headers array

Map of header name to header value.


WP_REST_Server:: serve_request( string $path = null )

Handles serving an API request. Since 4.4.0.

Matches the current server URI to a route and runs the first matching callback then outputs a JSON representation of the returned value.

Arguments

Name Type(s) Default Value Description
$path string

Optional. The request route. If not set, $_SERVER['PATH_INFO'] will be used. Default null.

Returns

false | null

Null if not served and a HEAD request, false otherwise.


WP_REST_Server:: set_status( integer $code )

Sends an HTTP status code. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$code integer

HTTP status.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.