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


  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

  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 •

  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.