Presentation on extending the WordPress REST API -- modifying default responses and creating custom endpoints http://joshpress.net/extending-rest-api-talk

1. Extending The
WordPress REST
API
Josh Pollock

2. Hi, I'm Josh
Slides: JoshPress.net/extending-rest-api-talk

3. What We Are Covering
Extending The Default
Responses
v2.wp-api.
org/extending/modifyi
Creating Your Own
Endpoints
v2.wp-api.
org/extending/adding/

4. We're Skipping To The Back of The Book:)
Download: wpeng.in/wp-api-ebook/

5. Let's Talk About Defaults

6. Why Extend The Defaults?
Are endpoints of a default endpoint close, but
missing a field?
Combine POST requests.
add_filter( 'the_content', function( $content ) { …
add_filter( 'template_includes', function( $template ) { ...

7. Why Make Your Own?
● Unique data sets -- custom queries, custom
tables, wrapping existing classes.
● Just the data you need.
● Replace admin-ajax
$query = new WP_Query( $args );
$collection = new my_class( $params );
global $wpdb;
add_rewrite_rule('^leaf/([0-9]+)/?', 'index.php?page_id=$matches[1]', 'top');

8. Anatomy Of A REST Request
WP_REST_SERVER ??WP_REST_Request WP_REST_Response

9. Extending Defaults

10. Customizing Default Routes
● Add fields to response
○ Custom field or any other data
● Applies to all read and/or write endpoints of
route.

11. Meet register_api_field()
http://v2.wp-api.org/extending/modifying/
● Adds fields to one or more response
● Arguments:
○ Object (post type name or "terms", "meta", "user" or
"comments" )
○ Name of field
○ Args
■ Read Callback
■ Write Callback
■ Schema Callback

12. Example Handlers
function slug_get_meta_field( $object, $field_name, $request ) {
return get_post_meta( $object[ 'id' ], $field_name );
}
public function slug_update_meta( $value, $object, $field_name ) {
if ( ! $value || ! is_string( $value ) ) {
return;
}
return update_post_meta( $object->ID, $field_name, strip_tags(
$value ) );
}

13. Example Registration
add_action( 'rest_api_init', 'slug_register_spaceship' );
function slug_register_spaceship() {
register_api_field( 'post',
'starship',
array(
'get_callback' => slug_get_meta_field,
'update_callback' => slug_update_meta_field,
'schema' => null,
)
);
}

14. Adding Your Own Endpoints

15. Anatomy Of A REST Request
WP_REST_SERVER Your RouteWP_REST_Request WP_REST_Response

16. Request -> Callback -> Response
Check Permission Validate Fields Sanitize Fields
Callback
Response

17. Meet register_rest_route()
http://v2.wp-api.org/extending/adding/
Adds a collection of routes.
add_action( 'rest_api_init', function () {
register_rest_route( 'myplugin/v1', '/author/(?
P<id>d+)', array(
'methods' => 'GET',
'callback' => 'my_awesome_func',
) );
} );

18. Namespacing & Versioning

19. register_rest_route() Defines
● Endpoints For Route
● Permissions for endpoints
● Transport methods for endpoints
● Fields for endpoints
● Callback for endpoints
● Schema

20. Endpoint URL
public function the_route() {
register_rest_route( 'swp_api', '/search',
array( )
);
}
Namespace
Route

21. Transport Method
public function the_route() {
register_rest_route( 'swp_api', '/search',
array(
'methods' => WP_REST_Server::READABLE,
)
);
}
GET

22. Permissions
public function the_route() {
register_rest_route( 'swp_api', '/search',
array(
'methods' => WP_REST_Server::READABLE,
'permission_callback' => array( $this, 'permissions_check' )
)
);
}

23. Permissions
public function permissions_check( $request ) {
$allowed = apply_filters( 'cwp_swp_api_allow_query', true, $request );
return (bool) $allowed;
}
public function permissions_check( $request ) {
return current_user_can( 'something' );
}
Standard WordPress Permissions/ Authentication!!!!!!!!!

24. Fields
public function the_route() {
register_rest_route( 'swp_api', '/search',
array(
'methods' => WP_REST_Server::READABLE,
'permission_callback' => array( $this, 'permissions_check' ),
'args' => $this->the_args(),
)
);
}

25. Fields
$args = array(
's' => array(
'default' => '',
'sanitize_callback' => 'sanitize_text_field',
),
'engine' => array(
'default' => 'default',
'sanitize_callback' => 'sanitize_text_field',
'validate_callback' => array( $this, 'validate_engine' ),
),
'page' => array(
'default' => 1,
'sanitize_callback' => 'absint',
),
);

26. Callback
public function the_route() {
register_rest_route( 'swp_api', '/search',
array(
'methods' => WP_REST_Server::READABLE,
'permission_callback' => array( $this, 'permissions_check' ),
'args' => $this->the_args(),
'callback' => array( $this, 'callback' ),
)
);
}

27. Callback
public function callback( $request ) {
$params = $request->get_params();
$cb_class = new class_that_does_something( $params );
$results = $cb_class->get_results();
if( is_array( $results ) {
return rest_ensure_response( $results, 200 );
}elseif( is_wp_error( $results ) ) {
return rest_ensure_response( $results, 500 );
}else{
return rest_ensure_response( __( 'FAIL!', 'text-domain' ), 500 );
}
}

28. Response
Should be either:
● An instance of WP_REST_Response
● An instance of WP_Error
rest_ensure_response( $data, $code, $headers );

29. You're Ready To Learn More
JoshPress.net/extending-rest-api-talk
wpeng.in/wp-api-ebook/
That's About It

30. JoshPress.net
CalderaWP.com
@Josh412
Josh Pollock