[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> rest-api.php (summary)

REST API functions.

File Size: 3430 lines (98 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 83 functions

  register_rest_route()
  register_rest_field()
  rest_api_init()
  rest_api_register_rewrites()
  rest_api_default_filters()
  create_initial_rest_routes()
  rest_api_loaded()
  rest_get_url_prefix()
  get_rest_url()
  rest_url()
  rest_do_request()
  rest_get_server()
  rest_ensure_request()
  rest_ensure_response()
  rest_handle_deprecated_function()
  rest_handle_deprecated_argument()
  rest_handle_doing_it_wrong()
  rest_send_cors_headers()
  rest_handle_options_request()
  rest_send_allow_header()
  _rest_array_intersect_key_recursive()
  rest_filter_response_fields()
  rest_is_field_included()
  rest_output_rsd()
  rest_output_link_wp_head()
  rest_output_link_header()
  rest_cookie_check_errors()
  rest_cookie_collect_status()
  rest_application_password_collect_status()
  rest_get_authenticated_app_password()
  rest_application_password_check_errors()
  rest_add_application_passwords_to_index()
  rest_get_avatar_urls()
  rest_get_avatar_sizes()
  rest_parse_date()
  rest_parse_hex_color()
  rest_get_date_with_gmt()
  rest_authorization_required_code()
  rest_validate_request_arg()
  rest_sanitize_request_arg()
  rest_parse_request_arg()
  rest_is_ip_address()
  rest_sanitize_boolean()
  rest_is_boolean()
  rest_is_integer()
  rest_is_array()
  rest_sanitize_array()
  rest_is_object()
  rest_sanitize_object()
  rest_get_best_type_for_value()
  rest_handle_multi_type_schema()
  rest_validate_array_contains_unique_items()
  rest_stabilize_value()
  rest_validate_json_schema_pattern()
  rest_find_matching_pattern_property_schema()
  rest_format_combining_operation_error()
  rest_get_combining_operation_error()
  rest_find_any_matching_schema()
  rest_find_one_matching_schema()
  rest_are_values_equal()
  rest_validate_enum()
  rest_get_allowed_schema_keywords()
  rest_validate_value_from_schema()
  rest_validate_null_value_from_schema()
  rest_validate_boolean_value_from_schema()
  rest_validate_object_value_from_schema()
  rest_validate_array_value_from_schema()
  rest_validate_number_value_from_schema()
  rest_validate_string_value_from_schema()
  rest_validate_integer_value_from_schema()
  rest_sanitize_value_from_schema()
  rest_preload_api_request()
  rest_parse_embed_param()
  rest_filter_response_by_context()
  rest_default_additional_properties_to_false()
  rest_get_route_for_post()
  rest_get_route_for_post_type_items()
  rest_get_route_for_term()
  rest_get_route_for_taxonomy_items()
  rest_get_queried_resource_route()
  rest_get_endpoint_args_for_schema()
  rest_convert_error_to_response()
  wp_is_rest_endpoint()

Functions
Functions that are not part of a class:

register_rest_route( $route_namespace, $route, $args = array()   X-Ref
Registers a REST API route.

Note: Do not use before the {@see 'rest_api_init'} hook.

param: string $route_namespace The first URL segment after core prefix. Should be unique to your package/plugin.
param: string $route           The base URL for route you are adding.
param: array  $args            Optional. Either an array of options for the endpoint, or an array of arrays for
param: bool   $override        Optional. If the route already exists, should we override it? True overrides,
return: bool True on success, false on error.

register_rest_field( $object_type, $attribute, $args = array()   X-Ref
Registers a new field on an existing WordPress object type.

param: string|array $object_type Object(s) the field is being registered to,
param: string       $attribute   The attribute name.
param: array        $args {

rest_api_init()   X-Ref
Registers rewrite rules for the REST API.


rest_api_register_rewrites()   X-Ref
Adds REST rewrite rules.


rest_api_default_filters()   X-Ref
Registers the default REST API filters.

Attached to the {@see 'rest_api_init'} action
to make testing and disabling these filters easier.


create_initial_rest_routes()   X-Ref
Registers default REST API routes.


rest_api_loaded()   X-Ref
Loads the REST API.


rest_get_url_prefix()   X-Ref
Retrieves the URL prefix for any API resource.

return: string Prefix.

get_rest_url( $blog_id = null, $path = '/', $scheme = 'rest' )   X-Ref
Retrieves the URL to a REST endpoint on a site.

Note: The returned URL is NOT escaped.

param: int|null $blog_id Optional. Blog ID. Default of null returns URL for current blog.
param: string   $path    Optional. REST route. Default '/'.
param: string   $scheme  Optional. Sanitization scheme. Default 'rest'.
return: string Full URL to the endpoint.

rest_url( $path = '', $scheme = 'rest' )   X-Ref
Retrieves the URL to a REST endpoint.

Note: The returned URL is NOT escaped.

param: string $path   Optional. REST route. Default empty.
param: string $scheme Optional. Sanitization scheme. Default 'rest'.
return: string Full URL to the endpoint.

rest_do_request( $request )   X-Ref
Do a REST request.

Used primarily to route internal requests through WP_REST_Server.

param: WP_REST_Request|string $request Request.
return: WP_REST_Response REST response.

rest_get_server()   X-Ref
Retrieves the current REST server instance.

Instantiates a new instance if none exists already.

return: WP_REST_Server REST server instance.

rest_ensure_request( $request )   X-Ref
Ensures request arguments are a request object (for consistency).

param: array|string|WP_REST_Request $request Request to check.
return: WP_REST_Request REST request instance.

rest_ensure_response( $response )   X-Ref
Ensures a REST response is a response object (for consistency).

This implements WP_REST_Response, allowing usage of `set_status`/`header`/etc
without needing to double-check the object. Will also allow WP_Error to indicate error
responses, so users should immediately check for this value.

param: WP_REST_Response|WP_Error|WP_HTTP_Response|mixed $response Response to check.
return: WP_REST_Response|WP_Error If response generated an error, WP_Error, if response

rest_handle_deprecated_function( $function_name, $replacement, $version )   X-Ref
Handles _deprecated_function() errors.

param: string $function_name The function that was called.
param: string $replacement   The function that should have been called.
param: string $version       Version.

rest_handle_deprecated_argument( $function_name, $message, $version )   X-Ref
Handles _deprecated_argument() errors.

param: string $function_name The function that was called.
param: string $message       A message regarding the change.
param: string $version       Version.

rest_handle_doing_it_wrong( $function_name, $message, $version )   X-Ref
Handles _doing_it_wrong errors.

param: string      $function_name The function that was called.
param: string      $message       A message explaining what has been done incorrectly.
param: string|null $version       The version of WordPress where the message was added.

rest_send_cors_headers( $value )   X-Ref
Sends Cross-Origin Resource Sharing headers with API requests.

param: mixed $value Response data.
return: mixed Response data.

rest_handle_options_request( $response, $handler, $request )   X-Ref
Handles OPTIONS requests for the server.

This is handled outside of the server code, as it doesn't obey normal route
mapping.

param: mixed           $response Current response, either response or `null` to indicate pass-through.
param: WP_REST_Server  $handler  ResponseHandler instance (usually WP_REST_Server).
param: WP_REST_Request $request  The request that was used to make current response.
return: WP_REST_Response Modified response, either response or `null` to indicate pass-through.

rest_send_allow_header( $response, $server, $request )   X-Ref
Sends the "Allow" header to state all methods that can be sent to the current route.

param: WP_REST_Response $response Current response being served.
param: WP_REST_Server   $server   ResponseHandler instance (usually WP_REST_Server).
param: WP_REST_Request  $request  The request that was used to make current response.
return: WP_REST_Response Response to be served, with "Allow" header if route has allowed methods.

_rest_array_intersect_key_recursive( $array1, $array2 )   X-Ref
Recursively computes the intersection of arrays using keys for comparison.

param: array $array1 The array with master keys to check.
param: array $array2 An array to compare keys against.
return: array An associative array containing all the entries of array1 which have keys

rest_filter_response_fields( $response, $server, $request )   X-Ref
Filters the REST API response to include only an allow-listed set of response object fields.

param: WP_REST_Response $response Current response being served.
param: WP_REST_Server   $server   ResponseHandler instance (usually WP_REST_Server).
param: WP_REST_Request  $request  The request that was used to make current response.
return: WP_REST_Response Response to be served, trimmed down to contain a subset of fields.

rest_is_field_included( $field, $fields )   X-Ref
Given an array of fields to include in a response, some of which may be
`nested.fields`, determine whether the provided field should be included
in the response body.

If a parent field is passed in, the presence of any nested field within
that parent will cause the method to return `true`. For example "title"
will return true if any of `title`, `title.raw` or `title.rendered` is
provided.

param: string $field  A field to test for inclusion in the response body.
param: array  $fields An array of string fields supported by the endpoint.
return: bool Whether to include the field or not.

rest_output_rsd()   X-Ref
Adds the REST API URL to the WP RSD endpoint.


rest_output_link_wp_head()   X-Ref
Outputs the REST API link tag into page header.


rest_output_link_header()   X-Ref
Sends a Link header for the REST API.


rest_cookie_check_errors( $result )   X-Ref
Checks for errors when using cookie-based authentication.

WordPress' built-in cookie authentication is always active
for logged in users. However, the API has to check nonces
for each request to ensure users are not vulnerable to CSRF.

param: WP_Error|mixed $result Error from another authentication handler,
return: WP_Error|mixed|bool WP_Error if the cookie is invalid, the $result, otherwise true.

rest_cookie_collect_status()   X-Ref
Collects cookie authentication status.

Collects errors from wp_validate_auth_cookie for use by rest_cookie_check_errors.


rest_application_password_collect_status( $user_or_error, $app_password = array()   X-Ref
Collects the status of authenticating with an application password.

param: WP_Error $user_or_error The authenticated user or error instance.
param: array    $app_password  The Application Password used to authenticate.

rest_get_authenticated_app_password()   X-Ref
Gets the Application Password used for authenticating the request.

return: string|null The Application Password UUID, or null if Application Passwords was not used.

rest_application_password_check_errors( $result )   X-Ref
Checks for errors when using application password-based authentication.

param: WP_Error|null|true $result Error from another authentication handler,
return: WP_Error|null|true WP_Error if the application password is invalid, the $result, otherwise true.

rest_add_application_passwords_to_index( $response )   X-Ref
Adds Application Passwords info to the REST API index.

param: WP_REST_Response $response The index response object.
return: WP_REST_Response

rest_get_avatar_urls( $id_or_email )   X-Ref
Retrieves the avatar URLs in various sizes.

param: mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash,
return: (string|false)[] Avatar URLs keyed by size. Each value can be a URL string or boolean false.

rest_get_avatar_sizes()   X-Ref
Retrieves the pixel sizes for avatars.

return: int[] List of pixel sizes for avatars. Default `[ 24, 48, 96 ]`.

rest_parse_date( $date, $force_utc = false )   X-Ref
Parses an RFC3339 time into a Unix timestamp.

param: string $date      RFC3339 timestamp.
param: bool   $force_utc Optional. Whether to force UTC timezone instead of using
return: int Unix timestamp.

rest_parse_hex_color( $color )   X-Ref
Parses a 3 or 6 digit hex color (with #).

param: string $color 3 or 6 digit hex color (with #).
return: string|false

rest_get_date_with_gmt( $date, $is_utc = false )   X-Ref
Parses a date into both its local and UTC equivalent, in MySQL datetime format.

param: string $date   RFC3339 timestamp.
param: bool   $is_utc Whether the provided date should be interpreted as UTC. Default false.
return: array|null {

rest_authorization_required_code()   X-Ref
Returns a contextual HTTP error code for authorization failure.

return: int 401 if the user is not logged in, 403 if the user is logged in.

rest_validate_request_arg( $value, $request, $param )   X-Ref
Validate a request argument based on details registered to the route.

param: mixed           $value
param: WP_REST_Request $request
param: string          $param
return: true|WP_Error

rest_sanitize_request_arg( $value, $request, $param )   X-Ref
Sanitize a request argument based on details registered to the route.

param: mixed           $value
param: WP_REST_Request $request
param: string          $param
return: mixed

rest_parse_request_arg( $value, $request, $param )   X-Ref
Parse a request argument based on details registered to the route.

Runs a validation check and sanitizes the value, primarily to be used via
the `sanitize_callback` arguments in the endpoint args registration.

param: mixed           $value
param: WP_REST_Request $request
param: string          $param
return: mixed

rest_is_ip_address( $ip )   X-Ref
Determines if an IP address is valid.

Handles both IPv4 and IPv6 addresses.

param: string $ip IP address.
return: string|false The valid IP address, otherwise false.

rest_sanitize_boolean( $value )   X-Ref
Changes a boolean-like value into the proper boolean value.

param: bool|string|int $value The value being evaluated.
return: bool Returns the proper associated boolean value.

rest_is_boolean( $maybe_bool )   X-Ref
Determines if a given value is boolean-like.

param: bool|string $maybe_bool The value being evaluated.
return: bool True if a boolean, otherwise false.

rest_is_integer( $maybe_integer )   X-Ref
Determines if a given value is integer-like.

param: mixed $maybe_integer The value being evaluated.
return: bool True if an integer, otherwise false.

rest_is_array( $maybe_array )   X-Ref
Determines if a given value is array-like.

param: mixed $maybe_array The value being evaluated.
return: bool

rest_sanitize_array( $maybe_array )   X-Ref
Converts an array-like value to an array.

param: mixed $maybe_array The value being evaluated.
return: array Returns the array extracted from the value.

rest_is_object( $maybe_object )   X-Ref
Determines if a given value is object-like.

param: mixed $maybe_object The value being evaluated.
return: bool True if object like, otherwise false.

rest_sanitize_object( $maybe_object )   X-Ref
Converts an object-like value to an array.

param: mixed $maybe_object The value being evaluated.
return: array Returns the object extracted from the value as an associative array.

rest_get_best_type_for_value( $value, $types )   X-Ref
Gets the best type for a value.

param: mixed    $value The value to check.
param: string[] $types The list of possible types.
return: string The best matching type, an empty string if no types match.

rest_handle_multi_type_schema( $value, $args, $param = '' )   X-Ref
Handles getting the best type for a multi-type schema.

This is a wrapper for {@see rest_get_best_type_for_value()} that handles
backward compatibility for schemas that use invalid types.

param: mixed  $value The value to check.
param: array  $args  The schema array to use.
param: string $param The parameter name, used in error messages.
return: string

rest_validate_array_contains_unique_items( $input_array )   X-Ref
Checks if an array is made up of unique items.

param: array $input_array The array to check.
return: bool True if the array contains unique items, false otherwise.

rest_stabilize_value( $value )   X-Ref
Stabilizes a value following JSON Schema semantics.

For lists, order is preserved. For objects, properties are reordered alphabetically.

param: mixed $value The value to stabilize. Must already be sanitized. Objects should have been converted to arrays.
return: mixed The stabilized value.

rest_validate_json_schema_pattern( $pattern, $value )   X-Ref
Validates if the JSON Schema pattern matches a value.

param: string $pattern The pattern to match against.
param: string $value   The value to check.
return: bool           True if the pattern matches the given value, false otherwise.

rest_find_matching_pattern_property_schema( $property, $args )   X-Ref
Finds the schema for a property using the patternProperties keyword.

param: string $property The property name to check.
param: array  $args     The schema array to use.
return: array|null      The schema of matching pattern property, or null if no patterns match.

rest_format_combining_operation_error( $param, $error )   X-Ref
Formats a combining operation error into a WP_Error object.

param: string $param The parameter name.
param: array $error  The error details.
return: WP_Error

rest_get_combining_operation_error( $value, $param, $errors )   X-Ref
Gets the error of combining operation.

param: array  $value  The value to validate.
param: string $param  The parameter name, used in error messages.
param: array  $errors The errors array, to search for possible error.
return: WP_Error      The combining operation error.

rest_find_any_matching_schema( $value, $args, $param )   X-Ref
Finds the matching schema among the "anyOf" schemas.

param: mixed  $value   The value to validate.
param: array  $args    The schema array to use.
param: string $param   The parameter name, used in error messages.
return: array|WP_Error The matching schema or WP_Error instance if all schemas do not match.

rest_find_one_matching_schema( $value, $args, $param, $stop_after_first_match = false )   X-Ref
Finds the matching schema among the "oneOf" schemas.

param: mixed  $value                  The value to validate.
param: array  $args                   The schema array to use.
param: string $param                  The parameter name, used in error messages.
param: bool   $stop_after_first_match Optional. Whether the process should stop after the first successful match.
return: array|WP_Error                The matching schema or WP_Error instance if the number of matching schemas is not equal to one.

rest_are_values_equal( $value1, $value2 )   X-Ref
Checks the equality of two values, following JSON Schema semantics.

Property order is ignored for objects.

Values must have been previously sanitized/coerced to their native types.

param: mixed $value1 The first value to check.
param: mixed $value2 The second value to check.
return: bool True if the values are equal or false otherwise.

rest_validate_enum( $value, $args, $param )   X-Ref
Validates that the given value is a member of the JSON Schema "enum".

param: mixed  $value  The value to validate.
param: array  $args   The schema array to use.
param: string $param  The parameter name, used in error messages.
return: true|WP_Error True if the "enum" contains the value or a WP_Error instance otherwise.

rest_get_allowed_schema_keywords()   X-Ref
Get all valid JSON schema properties.

return: string[] All valid JSON schema properties.

rest_validate_value_from_schema( $value, $args, $param = '' )   X-Ref
Validate a value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_null_value_from_schema( $value, $param )   X-Ref
Validates a null value based on a schema.

param: mixed  $value The value to validate.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_boolean_value_from_schema( $value, $param )   X-Ref
Validates a boolean value based on a schema.

param: mixed  $value The value to validate.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_object_value_from_schema( $value, $args, $param )   X-Ref
Validates an object value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_array_value_from_schema( $value, $args, $param )   X-Ref
Validates an array value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_number_value_from_schema( $value, $args, $param )   X-Ref
Validates a number value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_string_value_from_schema( $value, $args, $param )   X-Ref
Validates a string value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_validate_integer_value_from_schema( $value, $args, $param )   X-Ref
Validates an integer value based on a schema.

param: mixed  $value The value to validate.
param: array  $args  Schema array to use for validation.
param: string $param The parameter name, used in error messages.
return: true|WP_Error

rest_sanitize_value_from_schema( $value, $args, $param = '' )   X-Ref
Sanitize a value based on a schema.

param: mixed  $value The value to sanitize.
param: array  $args  Schema array to use for sanitization.
param: string $param The parameter name, used in error messages.
return: mixed|WP_Error The sanitized value or a WP_Error instance if the value cannot be safely sanitized.

rest_preload_api_request( $memo, $path )   X-Ref
Append result of internal request to REST API for purpose of preloading data to be attached to a page.
Expected to be called in the context of `array_reduce`.

param: array  $memo Reduce accumulator.
param: string $path REST API path to preload.
return: array Modified reduce accumulator.

rest_parse_embed_param( $embed )   X-Ref
Parses the "_embed" parameter into the list of resources to embed.

param: string|array $embed Raw "_embed" parameter value.
return: true|string[] Either true to embed all embeds, or a list of relations to embed.

rest_filter_response_by_context( $response_data, $schema, $context )   X-Ref
Filters the response to remove any fields not available in the given context.

param: array|object $response_data The response data to modify.
param: array        $schema        The schema for the endpoint used to filter the response.
param: string       $context       The requested context.
return: array|object The filtered response data.

rest_default_additional_properties_to_false( $schema )   X-Ref
Sets the "additionalProperties" to false by default for all object definitions in the schema.

param: array $schema The schema to modify.
return: array The modified schema.

rest_get_route_for_post( $post )   X-Ref
Gets the REST API route for a post.

param: int|WP_Post $post Post ID or post object.
return: string The route path with a leading slash for the given post,

rest_get_route_for_post_type_items( $post_type )   X-Ref
Gets the REST API route for a post type.

param: string $post_type The name of a registered post type.
return: string The route path with a leading slash for the given post type,

rest_get_route_for_term( $term )   X-Ref
Gets the REST API route for a term.

param: int|WP_Term $term Term ID or term object.
return: string The route path with a leading slash for the given term,

rest_get_route_for_taxonomy_items( $taxonomy )   X-Ref
Gets the REST API route for a taxonomy.

param: string $taxonomy Name of taxonomy.
return: string The route path with a leading slash for the given taxonomy.

rest_get_queried_resource_route()   X-Ref
Gets the REST route for the currently queried object.

return: string The REST route of the resource, or an empty string if no resource identified.

rest_get_endpoint_args_for_schema( $schema, $method = WP_REST_Server::CREATABLE )   X-Ref
Retrieves an array of endpoint arguments from the item schema and endpoint method.

param: array  $schema The full JSON schema for the endpoint.
param: string $method Optional. HTTP method of the endpoint. The arguments for `CREATABLE` endpoints are
return: array The endpoint arguments.

rest_convert_error_to_response( $error )   X-Ref
Converts an error to a response object.

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

param: WP_Error $error WP_Error instance.
return: WP_REST_Response List of associative arrays with code and message keys.

wp_is_rest_endpoint()   X-Ref
No description



Generated : Tue Mar 19 08:20:01 2024 Cross-referenced by PHPXref