How to: create a custom endpoint with the core REST API in WordPress

WP REST api banner

It’s already been a while since the WP REST API infrastructure has been merged in to core. In the meantime the development of the full WP REST API continues with the development of the WP REST API plugin.

While if you want to use the full power of the WP REST API you still have to install the plugin waiting for it to be merged into core. However if you just need a single API endpoint for your website the infrastructure in core is already sufficiënt for your needs.

In this howto I’ll show you how to create a simple custom endpoint in the WP API, in my example the endpoint is used to fill a select2 input field via AJAX. On the other end of the endpoint, data is being received from a third party API via wp_remote_get (cURL).

This howto has been created based on WordPress 4.4.1.

The following code goes into your themes functions.php file, you can also put the code in a custom made plugin if that suits your needs better.

The first thing we need to do is to create the actual endpoint, this is done by registring the endpoint to the WP REST API via the action rest_api_init.

Example:

In this example we use the function register_rest_route to add the route /search to the WP REST API under the namespace ‘somename’. In the arguments we specified the methods that this route accepts, we will only retrieve data so GET will be enought. Other available methods would be: POST, PUT, DELETE etc. Keep it RESTfull! 🙂 The other arg is the callback for the route. This is the function that will be called when the route is retrieved. Make sure you have added this empty callback function to prevent errors!

An endpoint with a variable ID looks like this: /search/(?P<id>\d+)

Now that the route is registred we should be able to see in the API document of your website. This JSON document can be found http://youwebsite.com/wp-json. This shoud look something like this:


The last thing we need to take a look at is our callback function, the $request_data variable received is a WP_REST_Request object containing all the information about the request like Headers, Files and GET parameters. In my example the GET parameters are very usefull as i’m using a GET parameter to submit a keyword to my search. Keep in mind that this object is protected, so functions like get_params() are needed to retrieve the data. More on public/protected/private functions can be read here.

The endpoint I ended up with: /somename/search?keyword=searchterm

The callback function itself can contain any logic, thats up to you. The important thing is that your function returns an array containing data. This can be a normal plain PHP array. All the formatting and JSON encoding is handled by the WP API core.

My callback function example, i’m retrieving data from a third party API.

This is basicly how you can create a simple endpoint to extend the WP REST API, a callback function can hold any logic imaginable creating infinite possibilities for the REST API. For everyone interested, below is the snip of how I used the endpoint in select2.

Further reading: Adding Custom Endpoints

This was actually the first English article I wrote on WordPress ever, I hope it helped you in some way. Any feedback is highly appreciated. Questions are welcome as well. You can leave a comment of send me a tweet!

@martijn94

5 thoughts on “How to: create a custom endpoint with the core REST API in WordPress”

  1. This is a great basic and straightforward tutorial! I would also like to see steps to authenticate the rest api, especially with the simple cookie authentication method.

  2. Great example that could well have saved me hours, your example is the only one of many that I found that explained the need for `$data->get_params`, in order to read protected objects. Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *