WordPress REST API - Writing Custom Endpoints

The WordPress rest API makes writing custom endpoints really easy. This presentation shows you how to get started.

Transcript

1. Custom Endpoints for the WordPress REST API
2. 2 parts to the WP Rest API • Infrastructure - Shipped in WP 4.4 • Core Endpoints - Due to ship in WP 4.7
3. REST API Infrastructure • Routing • HTTP method handling • Argument handling • JSON serialisation/deserialisation • Status codes • Permissions
4. Where to include your code? • Add your code using the rest_api_init action. • This ensures its only loaded when needed. https://gist.github.com/mattheu/afedf266e2b3ae0bb828c80ca1b15665
5. Register Endpoint Function: register_rest_route 1. Namespace. Unique string to prevent conflicts. Generally follow pattern test/v1. 2. Route. Supports regex. 3. Options. Specify request methods and callback function.
6. Register Endpoint Registers the route for GET requests. http://example.com/wp-json/wpleeds/v1/test- endpoint https://gist.github.com/mattheu/8afdaec300faa8f797ec55ae95ea8dc2
7. Register Endpoint: Callback https://gist.github.com/mattheu/8afdaec300faa8f797ec55ae95ea8dc2 • Receives the request object. • Returned data is output as JSON
8. Register Endpoint: Callback
9. Note on Route Names • Good APIs are easy to use and the routes you choose to use play a very important part. • They should be clear, readable and descriptive. • Good: /movies/mad-max • Poor: /api?type=movie&name=mad-max
10. Arguments You can pass parameters in various ways. • URL e.g. /movies/:name • Query params e.g./movies?year=2015 • Body e.g. POST requests • Files
11. Arguments: URL In order to pass arguments as part of the URL, you can use named capturing groups in your route regex. https://gist.github.com/mattheu/60e63342bb203760e23752e9383c977f
12. • Arguments are added to the request object. Using Arguments
13. Defining Arguments You can define the available arguments when registering your route. Arguments can have a number of settings. • Required • Default value • Sanitization callback • Validation callback
14. Defining Arguments
15. Defining Arguments
16. Request Methods • RESTful APIs use HTTP verbs to make requests more meaningful. • Specify supported methods when registering route. Endpoint only works when for these methods. • e.g. GET, POST, PUT, PATCH, DELETE. • You can have multiple endpoints at the the same route (URL) for different request methods.
17. Args: Request Methods • Aliases available on WP_REST_Server class • WP_REST_Server::READABLE === ‘GET’ • WP_REST_Server::CREATABLE === ‘POST’ • WP_REST_Server::EDITABLE === ‘POST, PUT, PATCH’ • WP_REST_Server::DELETABLE === ‘DELETE’ • WP_REST_Server::ALLMETHODS === 'GET, POST, PUT, PATCH, DELETE'
18. Custom Status Codes • Your endpoint callback can return WP_REST_Response object instead of just returning some data. • This allows you to customise the response setting headers and the status code.
19. Status Codes & Errors • Your endpoint callback can also return a WP_Error • Default is to trigger a 500 Internal Service Error response code • Set error status code by passing it as the 3rd parameter when creating the WP_Error [‘status’=>404]
20. Permissions • Permissions callback passed as option when registering route. • Return boolean. true if allowed, false if forbidden. • Requires an authenticated request. • On failure, returns 403 status with helpful error code and message.
21. Permissions
22. Why use custom endpoints? • AJAX. Replace use of admin-ajax.php • Conform to existing API specification. • Create simpler, lightweight endpoints.