<?php
/**
* This is our callback function that embeds our resource in a WP_REST_Response
*/
function prefix_get_colors($request) {
// In practice this function would fetch more practical data. Here we are just making stuff up.
$colors = array(
'blue',
'blue',
'red',
'red',
'green',
'green',
);
if (isset($request['filter'])) {
$filtered_colors = array();
foreach ($colors as $color) {
if ($request['filter'] === $color) {
$filtered_colors[] = $color;
}
}
return rest_ensure_response($filtered_colors);
}
return rest_ensure_response($colors);
}
/**
* Validate a request argument based on details registered to the route.
*
* @param mixed $value Value of the 'filter' argument.
* @param WP_REST_Request $request The current request object.
* @param string $param Key of the parameter. In this case it is 'filter'.
* @return WP_Error|boolean
*/
function prefix_filter_arg_validate_callback($value, $request, $param) {
// If the 'filter' argument is not a string return an error.
if (!is_string($value)) {
return new WP_Error('rest_invalid_param', esc_html__('The filter argument must be a string.', 'my-text-domain'), array('status' => 400));
}
// Get the registered attributes for this endpoint request.
$attributes = $request->get_attributes();
// Grab the filter param schema.
$args = $attributes['args'][$param];
// If the filter param is not a value in our enum then we should return an error as well.
if (!in_array($value, $args['enum'], true)) {
return new WP_Error('rest_invalid_param', sprintf(__('%s is not one of %s'), $param, implode(', ', $args['enum'])), array('status' => 400));
}
}
/**
* We can use this function to contain our arguments for the example product endpoint.
*/
function prefix_get_color_arguments() {
$args = array();
// Here we are registering the schema for the filter argument.
$args['filter'] = array(
// description should be a human readable description of the argument.
'description' => esc_html__('The filter parameter is used to filter the collection of colors', 'my-text-domain'),
// type specifies the type of data that the argument should be.
'type' => 'string',
// enum specified what values filter can take on.
'enum' => array('red', 'green', 'blue'),
// Here we register the validation callback for the filter argument.
'validate_callback' => 'prefix_filter_arg_validate_callback',
);
return $args;
}
/**
* This function is where we register our routes for our example endpoint.
*/
function prefix_register_example_routes() {
// register_rest_route() handles more arguments but we are going to stick to the basics for now.
register_rest_route('my-colors/v1', '/colors', array(
// By using this constant we ensure that when the WP_REST_Server changes our readable endpoints will work as intended.
'methods' => WP_REST_Server::READABLE,
// Here we register our callback. The callback is fired when this endpoint is matched by the WP_REST_Server class.
'callback' => 'prefix_get_colors',
// Here we register our permissions callback. The callback is fired before the main callback to check if the current user can access the endpoint.
'args' => prefix_get_color_arguments(),
));
}
add_action('rest_api_init', 'prefix_register_example_routes');
?>