Upgrade to Pro — share decks privately, control downloads, hide ads and more …

WordPress REST API - Writing Custom Endpoints

WordPress REST API - Writing Custom Endpoints

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

Matthew Haines-Young

October 25, 2016
Tweet

More Decks by Matthew Haines-Young

Other Decks in Technology

Transcript

  1. 2 parts to the WP Rest API • Infrastructure -

    Shipped in WP 4.4 • Core Endpoints - Due to ship in WP 4.7
  2. REST API Infrastructure • Routing • HTTP method handling •

    Argument handling • JSON serialisation/deserialisation • Status codes • Permissions
  3. 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
  4. 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.
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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.
  10. 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'
  11. 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.
  12. 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]
  13. 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.
  14. Why use custom endpoints? • AJAX. Replace use of admin-ajax.php

    • Conform to existing API specification. • Create simpler, lightweight endpoints.