Wordpress REST API, how to get /post schema? - wordpress

Question

I have created a custom endpoint, that basically just grabs a few different posts from each category and returns it. This endpoint works fine, but the schema of each post being returned is not the same as when you just hit the default, built-in /posts endpoint. What do I have to do to keep the schemas consistent?
I have a feeling get_posts is the problem, but I have been doc crawling, and I cant seem to find anything that uses the same schema as /posts does.
// How the endpoint is built.
function anon_content_api_posts($category) {
$posts = get_posts(
array(
'posts_per_page' => 3,
'tax_query' => array(
array(
'taxonomy' => 'content_category',
'field' => 'term_id',
'terms' => $category->term_id,
)
)
)
);
$posts = array_map('get_extra_post_data', $posts); // just me appending more data to each post.
return $posts;
}
function anon_content_api_resources() {
$data = array();
$categories = get_categories(
array(
'taxonomy' => 'content_category',
)
);
foreach($categories as $category) {
$category->posts = anon_content_api_posts($category);
array_push($data, $category);
}
return $data;
}
Custom endpoint schema
ID:
author:
comment_count:
comment_status:
featured_image_url:
filter:
guid:
menu_order:
ping_status:
pinged:
post_author:
post_content:
post_content_filtered:
post_date:
post_date_gmt:
post_excerpt:
post_mime_type:
post_modified:
post_modified_gmt:
post_name:
post_parent:
post_password:
post_status:
post_title:
post_type:
to_ping:
Default /posts schema
_links:
author:
categories:
comment_status:
content:
date:
date_gmt:
excerpt:
featured_image_url:
featured_media:
format:
guid:
id:
link:
meta:
modified:
modified_gmt:
ping_status:
slug:
status:
sticky:
task_category:
template:
title:
type:
Any help would be appreciated!

Answer 1

Although this question is older, I had a difficult time finding the answer to getting the schema myself, so I wanted to share what I found.
Short Answer (to getting the schema information back): Use OPTIONS method on the route request
You are dealing with an endpoint that already exists /wp/v2/posts, so you probably want to modify the response of the existing route which you can do with register_rest_field() (this should keep the appropriate schema for all exposed post columns / fields, but allows you to modify the schema for the fields you are now exposing as well):
Something like this:
function demo_plugin_extend_route_rest_api()
{
register_rest_field(
'post',
'unexposed_column_in_wp_posts_table',
array(
'get_callback' => function( $post_arr ) {
$post_obj = get_post( $post_arr['id'] );
return $post_obj->unexposed_column_in_wp_posts_table;
},
'update_callback' => function( $unexposed_column_in_wp_posts_table, $post_obj ) {
$ret = wp_update_post(
array(
// ID is the name of the column in the posts table
// unexposed_column_in_wp_posts_table should be replaced throughout with the unexposed column in the posts table
'ID' => $post_obj->ID,
'unexposed_column_in_wp_posts_table' => $unexposed_column_in_wp_posts_table
)
);
if ( false === $ret )
{
return new WP_Error(
'rest_post_unexposed_column_in_wp_posts_table_failed',
__( 'Failed to update unexposed_column_in_wp_posts_table.' ),
array( 'status' => 500 )
);
}
return true;
},
'schema' => array(
'description' => __( 'Post unexposed_column_in_wp_posts_table' ),
'type' => 'integer'
),
)
);
}
// Not-in-class call (use only this add_action or the one below, but not both)
add_action( 'rest_api_init', 'demo_plugin_extend_route_rest_api' );
// In-class call
add_action( 'rest_api_init', array($this, 'demo_plugin_extend_route_rest_api') );
If what you are really wanting is to create a new route and endpoint with custom tables (or another endpoint to the posts table), something like this should work:
function demo_plugin_custom_rest_api()
{
// Adding Custom Endpoints (add tables and fields not currently exposed)
// register_rest_route()
// $namespace (string) (Required) The first URL segment after core prefix.
// Should be unique to your package/plugin.
// $route (string) (Required) The base URL for route you are adding.
// $args (array) (Optional) Either an array of options for the endpoint, or an
// array of arrays for multiple methods. Default value: array()
// array: If using schema element to define the schema, or multiple methods,
// then wrap the 'methods', 'args', and 'permission_callback' in an array,
// otherwise they do not need to be wrapped in an array. Best practice
// would be to wrap them in an array though
// 'methods' (array | string): GET, POST, DELETE, PUT, PATCH, etc.
// 'args' (array)
// '<schema property name>' (array) (ie. parameter name - if not including a schema
// then can include field names as valid parameters as a way to
// describe them):
// 'default': Used as the default value for the argument, if none is supplied
// Note: (if defined, then it will validate and sanitize regardless of if
// the parameter is passed in query).
// 'required': If defined as true, and no value is passed for that argument, an
// error will be returned. No effect if a default value is set, as the argument
// will always have a value.
// 'description': Field Description
// 'type': Data Type
// 'validate_callback' (function): Used to pass a function that will be passed the
// value of the argument. That function should return true if the value is valid,
// and false if not.
// 'sanitize_callback' (function): Used to pass a function that is used to sanitize
// the value of the argument before passing it to the main callback.
// 'permission_callback' (function): Checks if the user can perform the
// action (reading, updating, etc) before the real callback is called
// 'schema' (callback function) (optional): Defines the schema.
// NOTE: Can view this schema information by making OPTIONS method request.
// $override (bool) (Optional) If the route already exists, should we override it? True overrides,
// false merges (with newer overriding if duplicate keys exist). Default value: false
//
// View your describe page at: /wp-json/demo-plugin/v1
// View your JSON data at: /wp-json/demo-plugin/v1/demo-plugin_options
// View your schema at (with OPTIONS method) at: /wp-json/demo-plugin/v1/demo-plugin_options
// Note: For a browser method to see OPTIONS Request in Firefox:
// Inspect the JSON data endpoint (goto endpoint and click F12)
// > goto Network
// > find a GET request
// > click it
// > goto headers section
// > click Edit and Resend
// > change Method to OPTIONS
// > click Send
// > double click on last OPTIONS request
// > goto Response (the JSON data returned shows your schema)
register_rest_route(
'demo-plugin/v1',
'/demo-plugin_options/',
array(
// GET array options
array(
'methods' => array('GET'),
'callback' => function ( WP_REST_Request $request ){
// Get Data (here we are getting from options, but could be any data retrieval)
$options_data = get_option('demo_option_name');
// Set $param
$param = $request->get_params();
// Do Other things based upon Params
return $options_data;
},
'args' => array(
// Valid Parameters
'element_1' => array(
'description'=> 'Element text field',
'type'=> 'string',
),
'element_color' => array(
'description'=> 'Element color select box',
'type'=> 'string',
)
)
),
// POST array options
array(
'methods' => array('POST'),
'callback' => function ( WP_REST_Request $request ){
// Get Data (here we are getting from options, but could be any data retrieval)
$options_data = get_option('demo_option_name');
// Set $param
$param = $request->get_params();
// Do Other things based upon Params
if (is_array($param) && isset($param))
{
foreach ($param as $k=>$v)
{
// $param is in an array($key => array($key => $value), ...)
if (is_array($v) && array_key_exists($k, $options_data) && array_key_exists($k, $v))
{
$options_data[$k] = $v;
}
}
}
update_option('demo_option_name', $options_data);
return $options_data;
},
'args' => array(
'element_1' => array(
'default' => '',
'required' => false,
'description'=> 'Element text field',
'type'=> 'string',
'validate_callback' => function($param, $request, $key) { //validation function },
'sanitize_callback' => function($param, $request, $key) { //sanitization function }
),
'element_color' => array(
'default' => 'red',
'required' => true,
'description'=> 'Element color select box',
'type'=> 'integer',
'validate_callback' => function($param, $request, $key) {
$colors = array('red', 'blue');
return in_array($param, $colors);
},
'sanitize_callback' => function($param, $request, $key) {
// If it includes a default, and sanitize callback for other properties above are set, it seems to need it here as well
return true;
})
),
'permission_callback' => function () {
// See Capabilities here: https://wordpress.org/support/article/roles-and-capabilities/
$approved = current_user_can( 'activate_plugins' );
return $approved;
}
),
'schema' => function() {
$schema = array(
// This tells the spec of JSON Schema we are using which is draft 4.
'$schema' => 'http://json-schema.org/draft-04/schema#',
// The title property marks the identity of the resource.
'title' => 'demo-plugin_options',
'type' => 'object',
// In JSON Schema you can specify object properties in the properties attribute.
'properties' => array(
'element_1' => array(
'description' => esc_html__( 'Element text field', 'demo-plugin' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => false,
),
'element_color' => array(
'description' => esc_html__( 'Element color select box', 'demo-plugin' ),
'type' => 'string',
'readonly' => false,
),
),
);
return $schema;
})
);
}
// Not-in-class call (use only this add_action or the one below, but not both)
add_action( 'rest_api_init', 'demo_plugin_custom_rest_api' );
// In-class call
add_action( 'rest_api_init', array($this, 'demo_plugin_custom_rest_api') );
Of course, this is just a basic outline. Here is a caveat:
According to the documentation listed below, it is best to use a Controller Pattern class extension method (rather than the method I outlined above): https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#the-controller-pattern
These were very helpful links in finally putting this all together for myself:
REST API Handbook: https://developer.wordpress.org/rest-api/
See Sub-Pages:
REST API Modifying Responses,
REST API Adding Custom Endpoints,
REST API Schema
Register REST Field Function: https://developer.wordpress.org/reference/functions/register_rest_field/
Register REST Route Function: https://developer.wordpress.org/reference/functions/register_rest_route/