DEV Community: David Woolf

Modify WordPress REST routes with register rest field

David Woolf — Tue, 28 Sep 2021 20:26:42 +0000

Getting Started

The register_rest_field function is a PHP function that allows you to add extra fields to any registered endpoint (posts, pages, custom post types, terms, users, etc). The function takes three parameters:



register_rest_field(
    $object_type,
    $attribute,
    $args
);

The $object_type parameter is any data type in WordPress, and can be an array of multiple types, or a string for a single type. Next, the $attribute parameter is the name of the field you want to register and will show up in the rest response as the key name.

Finally, the $args parameter is an array with a getter, setter, and schema definition. All three arguments are optional, so you have a lot of flexibility in how you control your field.

Registering a field

Let’s build a real example. In this case we’re going to register a field for posts that shows how many “slaps” the post has, along with a setter to add slaps whenever the user clicks a “slap this post” button.

First we want to target posts and name our attribute:



add_action('rest_api_init', function() {
    register_rest_field(
        'post',
        'slap_count',
        // ... getters and settings
    );
});

Note: wrap your register_rest_field calls in the rest_api_init action to ensures the rest api is loaded

Getting the value

While the above is the only required code to use the register_rest_field function, the field won’t show up in your REST endpoint without at least a get value. Let’s take care of that now:



add_action('rest_api_init', function() {
    register_rest_field(
        'post',
        'slap_count',
        // NEW CODE
        array(
            'get_callback' => function($object) {
                $slap_count = get_post_meta( $object['id'], 'slap_count', true );

                return $slap_count ? $slap_count : 0;
            }
        )
    );
});

The get_callback argument accepts an $object parameter, which in this case is an individual post (passed as an array). Inside of the callback we can use standard WordPress functions like get_post_meta. In this case, we are grabbing the slap_count meta field and returning either the value or 0.

If you query an single post using the /wp-json/wp/v2/posts/<id> endpoint, you should see this line in the response:



"slap_count": 0 // or whatever the value is

For our example, the field so far is pretty useless but if you just wanted to output a value directly then the above is all you need.

Setting the value

To allow updates to the value, add a update_callback argument to the $args array:



add_action('rest_api_init', function() {
    register_rest_field(
        'post',
        'slap_count',
        array(
            'get_callback' => function($object) {
                $slap_count = get_post_meta( $object['id'], 'slap_count', true );

                    return $slap_count ? $slap_count : 0;
            },
            // NEW CODE
            'update_callback' => function ( $value, $object ) {
                    $slap_count = get_post_meta( $object->ID, 'slap_count', true );

                    update_post_meta( $object->ID, 'slap_count', $slap_count + 1 );
            },
        )
    );
});

The update_callback function takes two parameters: $value and $object. In our case we aren’t using the value variable, but instead just adding 1 to the value whenever the callback is fired.

Note: in this function $object is passed as an object type instead of an array like get_callback.

Triggering an update

To actually fire the update_callback function, simply call the /wp-json/wp/v2/posts/<id> endpoint with the POST method, and pass the field name through the body as JSON:



// Javascript example
fetch('/wp-json/wp/v2/posts/1', {
    // make sure to authenticate or pass the X-WP-Nonce value as a header
    method: 'POST',
    body: JSON.stringify({
        "slap_count": 1 // reminder that the value doesn't matter for our example as we just increment the count by one
    })
})
.then(response => response.json())
.then(data => {
    // ... the updated post object is returned here
})
.catch(error => console.log('error', error));

Securing your field

As always, a little security goes a long way. The third parameter in the register_rest_field $args array is a schema array with sanitization and validation options:



add_action('rest_api_init', function() {
    register_rest_field(
        'post',
        'slap_count',
        array(
            // ...get_callback
            // ...update_callback

            // NEW CODE
            'schema' => array(
                'type' => 'string' // the type of value we expect to be passed back
                'sanitize_callback' => function($value) {
                    // run sanitization here
                    },
                    'validate_callback' => function ($value) {
                            // run sanitization here
                    },
            )
        )
    );
});

The schema parameter takes three arguments:

the type of the value (int, string, boolean, etc)
A sanitization callback to sanitize the input
A validate callback to make sure it conforms to some set of rules

If you haven’t already, read more on sanitizing and validating values accepted into your rest routes here. The same options can be used in the schema callback functions.

Wrap Up

In just a few lines of code, you can completely customize WordPress’ built-in REST routes with your own data. Or combine and extend existing values to avoid unnecessary work in Javascript and prevent multiple REST calls to grab necessary data.

Author

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

Generating WordPress Application Passwords for your third party apps

David Woolf — Wed, 08 Sep 2021 10:00:00 +0000

In our Postman walkthrough, we went over how to generate application passwords for a single user and pass it with each REST request to handle authentication. For real world use, asking users to go login to their account, generate a password, and copy it back into another app is a lot of friction. Luckily we can create a workflow to make this easier.

Note: we’ll be using Javascript and PHP for all examples in this article

Getting started

First, we need to verify the specific WordPress installation supports application passwords and if so, what the authorization url is (we’ll use this later to automate some of the steps to create a password). Assuming we know the website URL, we just need to do a GET request to the website’s main REST endpoint (wp-json):

fetch('https://theory.local/wp-json')
.then(response => response.json())
.then(body => {
      // check the authentication value here
})

Note: For these examples, I am using the Local app with SSL enabled. You must have an SSL connection to handle application password requests

Inside of our fetch statement, we’re requesting the wp-json endpoint which will return the overall API structure of the site as a JSON object. Inside this object, we’re looking for the authentication property. If it’s missing or empty, then we can’t do authentication on the site. If authentication is enabled, it will return an object that contains the authorization endpoint:

"authentication": {
    "application-passwords": {
        "endpoints": {
            "authorization": "<https://theory.local/wp-admin/authorize-application.php>"
        }
    }
}

If you go to that url and login, you’ll see something like the following:

Without passing in some parameters, it functions just like the application password section when editing a user in the dashboard. Here are the parameters we can pass:

app_name (required): human readable name (you app name, etc)
app_id (optional, but recommended): UUID string
success_url (optional, but recommended): the url to send the user to if they approve the connection. Supports multiple protocols, EXCEPT for the non-secure http://
reject_url (optional): the url to send the user to if they reject the application. Supports multiple protocols, EXCEPT for the non-secure http://

The success URL will be appended with three parameters: site_url, user_login, and password. Also, if you don’t pass a reject_url value, it will go to the success_url value and add ?success=false (this might be preferred if you want to manage everything from one page).

Creating your own app authentication

To provide an example of creating an application password for your app to connect to WordPress, we’re going to create a simple, local HTML/PHP form that takes the user to another local WordPress instance, generates the password and passes it back.

Setting up our form

Our form will be pretty basic, just an input to enter the website URL and a submit button (I’ve omitted styling code to make this more concise):

<form 
id="create-authentication-password"
action="/"
method="POST">
    <h1>
        Connect your site
    </h1>

    <label 
    for="website">
        <strong>
            Your Website URL
        </strong>

        <input 
        id="website"
        type="url" 
    name="website" 
    placeholder="https://"
    required
    pattern="https://.*">
    </label>

    <input
    type="submit" 
    value="Submit">
</form>

We’re using some newer technologies to quickly validate that the input is filled out and is a valid https url. Then we just have a standard submit button. Our form action is / because that’s the page URL I have it on, and we’ll be using Javascript to send the form. Here is how the form looks (again, I have CSS classes added):

Using Javascript to submit the form

We’re going to use ES6 syntax, and to get started we want to listen for the form submission:

<script type="javascript">
      document
      .getElementById('create-authentication-password')
      .addEventListener('submit', e => {
            e.preventDefault()

            // take action here...
      })
</script>

Next, we want to grab our input value. We can create a new FormData class, pass in our form and grab our input named website:

<script type="javascript">
      document
      .getElementById('create-authentication-password')
      .addEventListener('submit', e => {
            e.preventDefault()

            // NEW CODE
            const data = new FormData(e.target)
            const website = data.get('website')
    })
</script>

Next, we want to do our GET request on wp-json like we discussed initially:

<script type="javascript">
      document
      .getElementById('create-authentication-password')
      .addEventListener('submit', e => {
            e.preventDefault()

            const data = new FormData(e.target)
            const website = data.get('website')

            // NEW CODE
            fetch(`${website}/wp-json`)
            .then(response => response.json())
            .then(body => {
                  // do an action here
            })
      })
</script>

Finally, we’ll verify application support is available, grab the url to generate a new password, and pass in some parameters to redirect the user back:

<script type="javascript">
      document
      .getElementById('create-authentication-password')
      .addEventListener('submit', e => {
            e.preventDefault()

            const data = new FormData(e.target)
            const website = data.get('website')

            fetch(`${website}/wp-json`)
            .then(response => response.json())
            .then(body => {
                  // NEW CODE
                  if('authentication' in body && body.authentication !== false) {
                        const root = body.authentication['application-passwords'].endpoints.authorization
                        const params = '?app_name=Sandbox Website&success_url=https://sandbox.local/success'
                        window.location = `${root}${body}`
                  }
            })
      })
</script>

Let’s go over the new code line by line. First, we check for support with Javascript’s key in object code and ensure it’s not false:

if('authentication' in body && body.authentication !== false) {

Since the condition code will only fire if there is application password support, the rest of the code can setup the final url to go to:

const root = body.authentication['application-passwords'].endpoints.authorization
const params = '?app_name=Sandbox Website&success_url=https://sandbox.local/success'

Our root URL is the provided application password authorization URL from our fetch request. The params are a simply URL parameters string with our app name and success url (in production code, make sure to pass in an app_id).

Finally, we do a simple window.location page send with our root and body:

window.location = `${root}${body}`

This code will take the user to the inputted website and, if they click “Yes, I approve of this connection”, the site url, username, and application password will be sent back as URL parameters (this is why using https:// is important to prevent someone capturing these values). On my success page, I output these values as an example, and here’s what they look like:

Wrap Up

That’s all you need to create a simplified application password flow for your users! This is a basic authentication system where you pass back the username and password using base64 encryption. You should also make sure you encrypt the values when storing them to prevent security issues. Happy coding!

Author

.ltag__user__id__628430 .follow-action-button { background-color: #000000 !important; color: #ffffff !important; border-color: #000000 !important; }

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

Handling Permissions in your WordPress REST routes

David Woolf — Mon, 06 Sep 2021 09:00:00 +0000

In our previous walkthroughs on register_rest_route we added this line of code to our registration function:



'permission_callback' => '__return_true'

This was to prevent permissions issues for our sandbox code, but in a production environment you would only use this for fully public API endpoints, and never for endpoints related to a user.

Note: if you are building a public API then the above is what you should use.

Handling permissions in your routes

Just like validating user input for your route, the permissions callback is a function where you return either true, false, or a WP_Error instance:



register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>[a-zA-Z0-9_-]+)',
    array(
        array(
            // ... other arguments stripped for readability
            'permission_callback' => function($request) {
                // ... permissions check goes here
            },
        )
    )
);

The permissions callback is run after the current user is set, which would be either the matching user in the dashboard or an authenticated user you passed in your request. As this is WordPress, our permissions checks will use functions provided by WordPress, mainly current_user_can.

The callback also receives the entire request so you can perform conditional logic depending on the data passed in.

How to check user capabilities in WordPress

WordPress uses a roles and capabilities system to handle what a user is allowed to do. A role is basically a set of capabilities that you can quickly assign to users. Examples of built-in roles are administrator, author, editor, and subscriber.

A capability is a singular action a user is either allowed or not allowed to do. The system is additive, so if the user has the capability it means they can do the specified action (ie: don’t create capabilities like cannot_do_action.

The quickest way to verify a user can do something is by using the current_user_can function. This function takes a string that matches a capability and returns true or false:



return current_user_can('edit_posts'); // true or false

There are a lot of different capabilities built-in to WordPress, and you can add custom ones as well. We won’t go through the list, but you can view the list here https://wordpress.org/support/article/roles-and-capabilities/#capabilities

Performing a permissions check

Let’s go back to our rest route and add a permissions check. Let’s say theoretically that our route was to update global settings for the WordPress installation. We’ll use the built-in manage_options capability, which allows users to access and update all of the settings in the dashboard:



register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>[a-zA-Z0-9_-]+)',
    array(
        array(
            'permission_callback' => function($request) {
                return current_user_can('manage_options');
            },
        )
    )
);

Wrap Up

This was a short walkthrough, but that’s because creating permissions is pretty simple! It really just depends on how you design your user system and security levels (fortunately WordPress provides a lot of this up front for whats included out of the box). I would recommend looking closely at the capabilities provided. We’ll also go through creating capabilities and recommended plugins for more advanced patters like policies in the future.

Author

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

How to secure your REST API routes in WordPress

David Woolf — Wed, 01 Sep 2021 10:00:00 +0000

In our last article we looked at creating your own routes in the WordPress REST API using register_rest_route, along with some basic examples of requiring and checking for parameters. Today, we’ll go over a better way to handle validation and sanitization for data passed to your routes.

Where we left off before

Here is the final code we ended up with in our last session:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            array(
                'methods' => WP_REST_Server::READABLE,
                'callback' => 'callback_function',
                'permission_callback' => '__return_true'
            ),
            array(
                'methods' => WP_REST_Server::EDITABLE,
                'callback' => 'another_callback_function',
                'permission_callback' => '__return_true'
            )
        )
    );

    // our new route
    register_rest_route(
        'ndx/v1',
        'my-endpoint/(?P<id>\d+)',
        array(
            array(
                'methods' => WP_REST_Server::READABLE,
                'callback' => 'callback_function_with_id',
                'permission_callback' => '__return_true'
            )
        )
    );
}

We created a route called my-endpoint with GET and POST methods that do not require a parameter passed in, along with a similarly named route that requires an integer at the end (for example: my-endpoint/10).

Defining arguments

In our previous article, we created a new route that required an integer at the end:

// requires an id parameter, which must be a number
register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>\d+)',
    array(
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function_with_id',
            'permission_callback' => '__return_true'
        )
    )
);

Once again, here is how the regular expression defining the works:

'(?P<id>\\d+)' // the full argument (parathenses are to group it)
'?P' // denotes that this is a parameter
'<id>' // the name of the parameter
'\\d+' // indicates the paramter should be an integer

While regular expression are hard to read, this one takes care of a couple things we’ll cover in this article:

The route will not run if the id is missing (in our case, the original rest route will run, which can be intentional)
An error will be sent back if the id is not an integer (although it will just say the route doesn’t exist)

There are also a few of things this style won’t do:

The route won’t send a proper error back if the type is wrong (what if we want to let the user know they need to send an integer versus an ambiguous error about the route not existing)
The data won’t be sanitized in any custom way (for example: the ID needs to be less than 10)
We can’t pass in a default value

Adding additional checks for the argument:

To add the features described above, all we need to do is add an argument called args to our method:

register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>\\d+)',
    array(
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function_with_id',
            'permission_callback' => '__return_true',
            'args' => array(
                'id' => array(
                        // parameters go here
                )
            )
        )
    )
);

The args argument is a keyed array, with each key corresponding to the parameter. The key values are also an array with 4 options:

default: default value if the parameter is missing
required: set the parameter to be required or not
validate_callback: a function to validate something about the parameter. Returns true or false, and will send a formatted error back if false.
sanitize_callback: a function to sanitize the data before sending it to the callback

What’s interesting about these options is that, because of how we defined our parameter in our route name, we already have done most of this work:

the parameter is required
the parameter must be an integer

For testing, let’s change our route to pass in as many data types as possible:

register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>[a-zA-Z0-9_-]+)',
    array(
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function_with_id',
            'permission_callback' => '__return_true',
            'args' => array(
                'id' => array(
                )
            )
        )
    )
);

We now have a new regex expression (?P<id>[a-zA-Z0-9_-]+) which lets us pass in strings or numbers. Next, let’s add all of our available arguments into the args array:

register_rest_route(
    'ndx/v1',
    'my-endpoint/(?P<id>[a-zA-Z0-9_-]+)',
    array(
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function_with_id',
            'permission_callback' => '__return_true',
            'args' => array(
                'id' => array(
                    // NEW CODE HERE
                    'default' => 0,
                    'required' => true,
                    'validate_callback' => function($value, $request, $key) {
                        return true;
                    },
                    'sanitize_callback' => function($value, $request, $param) {
                        return $value;
                    }
                )
            )
        )
    )
);

The sample above has been coded to basically be useless. Validation always returns true and sanitization just returns the value untouched. Let’s break down each argument:

Default value

The default argument provides a default value if none is passed. Because we are encoding the parameter as part of the route name, this code will never be called. Not providing a value in the URL will either return an error that the route does not exist, or call another endpoint with the same name that does not have a parameter attached to the end (in our example, we have my-endpoint and my-endpoing/<id>.

Requiring a value

The required argument lets you defined an argument as required or not. Again, because we are encoding the parameter as part of the route name, this code will never be called.

Validation

Validating parameters is a great way to quickly check a parameter and say that it is either valid (true) or not valid (false). You only return true or false in validate_callback. Here is an example where an id greater than 10 will be considered invalid:

'validate_callback' => function($value, $request, $param) {
    return $value < 10;
}

Sanitization

Sanitization of parameters is different from validation because we return the value back in some form. Note that sanitize_callback and validate_callback do not get called in any specific order, and are simply additional filters to ensure whatever data passed in fits the logic of the original callback function. In our example, let’s remove negative numbers:

'sanitize_callback' => function($value, $request, $param) {
    $integer_value = (int) $value;

    return $integer_value < 0 ? 0 : $integer_value;     
}

Now, with our validate_callback and sanitize_callback functions we have ensured only numbers 0-10 are allowed to be passed through.

Additional arguments for quick validation and sanitization

There are a many more args for quickly validating a parameter without using function callbacks:

array(
    'type' => // array | object | integer | number | string | boolean | null
    'description' => // a description used in the API schema
    'format' => // hex-color | email | date-time | ip | uuid
    'enum' => // array of allowed values
    'minimum' => // minimum integer value (inclusive)
    'maximum' => // maximum integer value (inclusive)
    'exclusiveMinimum' => // minimum integer value (exclusive)
    'exclusiveMaximum' => // maximum integer value (exclusive)
);

Note: the format option requires the type to be defined as a string

Wrap up

Ensuring user input to any function, method or API should always be verified before taking action. While you can do all of the above in the full callback function for your route, it’s preferred to separate this out and prevent the callback from ever being fired if something is wrong.

I also want to make sure it’s stressed that you can (and should) create as many rules for any parameters used in your callback, not just the ones that might be defined as part of your endpoint name.

Author

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

How to create your own REST routes in WordPress

David Woolf — Mon, 30 Aug 2021 10:00:00 +0000

WordPress makes registering custom rest routes really easy with a function called register_rest_route. This function provides options to create a namespace (which you can also use to version your APIs), all of your route names, an args array to create CRUD operations and check security, and even set your route to override or merge with existing routes.

Function definition

Let’s review the function parameters and see what we can do:

register_rest_route(
    $namespace, 
    $route, 
    $args, 
    $override
);

namespace : a required string which should be the same for all of your routes in the api you are creating
route: the required string for the singular API endpoint, which would include some of the following methods: GET, POST, PUT, DELETE
args: optional array of options or array of array of options (we’ll go over this in detail)
override : optional true or false. True will replace an existing route while false will merge it and override any duplicate methods (defaults to false, so you can normally omit it)

Registering a route

To register a route, we need to call it inside of the rest_api_init hook:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        //...we'll work in here
    );
}

The first argument is the namespace. It’s important to note that your namespace should not include a beginning or trailing slash, and should be composed of your namespace and version number (for example, WordPress’s built-in routes use wp/v2):

// we'll omit the action hook line from the rest of the examples:
function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        // route name
        // args
    );
}

Next, we will create our route name. This will be the last part of the URL we call to access this route. Because this is a URL, you should name it the way you would see a URL (dashes instead of underscores, etc) and avoid characters like , % [] { } # ( ) * & and spaces:

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        // args
    );
}

Finally, we add our args. Because of the scope of the args parameter, we’ll be going over the basic pieces in the next section

Adding methods, permissions, and a callback function

The most basic use of the args parameter is this:

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            'methods' => 'GET',
            'callback' => 'callback_function' // this can any function name,
        )
    );
}

This small amount of code will create a new route with a GET method that calls the callback_function function. However, there are a couple of recommendations to make this better:

Permissions

With newer versions of WordPress, you are asked to set the permissions for your routes. It’s not required but you will get a warning message. To create a public route, just add this line to your args array:

array(
    'methods' => 'GET',
    'callback' => 'callback_function',
    'permission_callback' => '__return_true' // new permissions line
);

Another way to set methods

Because there are multiple methods that seem very similar (POST vs PUT etc), WordPress provides some constants as part of the WP_REST_Server class to make your method names more clear:

WP_REST_Server::READABLE // methods: GET
WP_REST_Server::EDITABLE // methods: POST, PUT, PATCH
WP_REST_Server::DELETABLE // methods: DELETE

You don’t need to instantiate the class so to use these just update the first line of your args statement:

array(
    'methods' => WP_REST_Server::READABLE // was previously 'GET'
    'callback' => 'callback_function',
    'permission_callback' => '__return_true'
);

That’s all you need to declare a basic route (minus the callback function of course). Let’s see the code all together:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function',
            'permission_callback' => '__return_true'
        )
    );
}

Creating your callback function

The callback function for your route is a normal PHP function, but it receives a full $request object as it’s parameter:

function callback_function($request) {
    // do stuff here
}

The $request parameter is a WP_Rest_Request instance and can contain body data, url parameters, and more. Now, let’s look at how we can return some data.

Returning data correctly

If you haven’t looked at our post on using rest_ensure_response I would give it a glance here. You can skip to the end to see an example. The function returns your data with a 200 OK response header and any type of data you pass back (strings, arrays, etc). Here is a useless return value for our new route:

function callback_function($request) {
    return rest_ensure_response('hello world!');
}

If you are working along with this article, you can test this yourself by adding the following to your base URL: /wp-json/ndx/v1/my-endpoint

Note: if you get a 404, it may be your permalinks. Go to Settings > Permalinks in the dashboard and turn on Pretty Permalinks. The specific style doesn’t matter, any of them will ensure /wp-json works correctly

If your route is setup correctly, you should see hello world! in the browser.

Testing URL parameters

Now that we can return data, it would be nice to read data sent along with the API. If you’ve ever used URL parameters before, this should be straightforward. Change your callback function to this:

function callback_function($request) {
    $name = $request->get_param('name');

    return rest_ensure_response("hello {$name}!");
}

Theget_param method is available from our WP_Rest_Response instance, and can be used to read any URL parameters passed with the route. To test this, add the following to your base URL:

/wp-json/ndx/v1/my-endpoint?name=YOUR NAME

You should see “hello YOUR NAME!”

Basic error handling

If you remove the name parameter from the URL the result looks malformed. We can handle this by checking for the name param in our callback function and returning an error if it’s missing:

function callback_function($request) {
    if(null !== $request->get_param('name')) {
        $name = $request->get_param('name');

        return rest_ensure_response("hello {$name}!");
    } else {
        return new WP_Error('missing_fields', 'please include name as a parameter');
    }
}

Note that there is a better way to handle required input, which we’ll cover in our next article about data sanitization, but this is a completely valid way to check for a value. Also, do not try to use isset with the get_param method, as it already checks for this and returns null if it can’t find the parameter.

Adding additional methods to your route

Let’s go back to our route registration code:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'callback_function',
            'permission_callback' => '__return_true'
        )
    );
}

If you wanted to add a POST method for your route, you might think of adding another register_rest_route function declaration. That would required duplicating a lot of code with the same values. Instead, let’s change our args array to be an array of arrays:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            array(
                'methods' => WP_REST_Server::READABLE,
                'callback' => 'callback_function',
                'permission_callback' => '__return_true'
            ),
            array(
                'methods' => WP_REST_Server::EDITABLE,
                'callback' => 'another_callback_function',
                'permission_callback' => '__return_true'
            )
        )
    );
}

Notice how we now have two arrays that are very similar, but the second one’s method is EDITABLE and the callback function is different. This means you’ll need to create another function to handle this endpoint:

function another_callback_function($request) {
    return rest_ensure_response('I show up when you call `my-endpoint` with the POST, PUT, or PATCH method');
}

If you add this code and refresh your browser you’ll notice you don’t see this message. That’s because accessing a WordPress API endpoint in the browser is always a GET request. To test other types of requests, you’ll need to use a library or something like Postman. We just posted a thorough tutorial on how to use Postman here.

Note: generally non-GET requests require authentication, but we are passing in our public permission callback, so you can skip that section of the Postman article and just get set up to play around with it.

Once you get set up in Postman, just make sure you change the method to POST, click the “Send” button and you should see this at the bottom:

Requiring values as part of the route

While URL parameters are a nice and flexible feature to send data to your route, you can also add data as part of the endpoint itself. For example, WordPress lets you access posts by going to wp-jons/wp/v2/posts but it also lets you look at a single post by going to /wp-json/wp/v2/posts/<id>. You can chain as many parameters as you want, although you will run into issues if some are required and some are not (what if the first parameter is optional, but the second isn’t?) It’s better to send multiple fields as URL parameters or body data.

If you do want to add a parameter as part of the endpoint, you do that to the $route argument in your register_rest_routefunction:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint/(?P<id>\d+)', // ADDED ID HERE
        // ...args
    );
}

The argument is wrapped in a regular expression, so let’s break it down:

'(?P<id>\\d+)' // the full argument (parathenses are to group it)
'?P' // denotes that this is a parameter
'<id>' // the name of the parameter
'\\d+' // indicates the paramter should be an integer

While this is hard to read, it does make sure the parameter is defined and has to be an integer. This change means the following calls are either valid or invalid:

/wp-json/ndx/v1/my-endpoint // not valid (missing the parameter)
/wp-json/ndx/v1/my-endpoint/10 // valid
/wp-json/ndx/v1/my-endpoint/hello // not valid (strings are not allowed)

To access the parameter in your callback function, just use get_param like before:

$request->get_param('id');

What if you wanted to make the parameter completely optional, like how WordPress does for posts? Just make a new route! Here’s the full code with our routes we created before the example above, plus our new one:

add_action('rest_api_init', 'register_your_routes');

function register_your_routes() {
    register_rest_route(
        'ndx/v1',
        'my-endpoint',
        array(
            array(
                'methods' => WP_REST_Server::READABLE,
                'callback' => 'callback_function',
                'permission_callback' => '__return_true'
            ),
            array(
                'methods' => WP_REST_Server::EDITABLE,
                'callback' => 'another_callback_function',
                'permission_callback' => '__return_true'
            )
        )
    );

    // our new route
    register_rest_route(
        'ndx/v1',
        'my-endpoint/(?P<id>\d+)',
        array(
            array(
                'methods' => WP_REST_Server::READABLE,
                'callback' => 'callback_function_with_id',
                'permission_callback' => '__return_true'
            )
        )
    );
}

Wrap Up

You are now ready to start creating your own routes! In our next article, we will go over the security features of register_rest_route like custom permissions, sanitizing data, and validating passed-in parameters, so you can create routes for real-world use.

Author

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

Using Postman with the WordPress REST API

David Woolf — Thu, 26 Aug 2021 15:23:03 +0000

Postman is a powerful tool to send URL requests and view the response data back. While you can do public GET requests in any browser, Postman offers the following:

POST, PUT, and DELETE requests (along with a bunch more)
Passing headers
Passing body data
Authentication
Viewing the response as different types of data
Saving your responses for use later

Sending your first request

First, make sure you download and install the Postman app from here. We'll be using the desktop version to walk through making requests and viewing the results.

Once the app is installed, you should see something like this:

To start making requests, just click the + icon next to the Overview tab in the main column.

In the top area of the new tab, you have a few options:

set the request type (defaults to GET)
enter your url
send the request
Add url parameters, authorization, headers, and body data (we will not be covering the other options in this article)

The fastest way to get started is to test a public GET request. Whether you're working locally or with a live site, you can enter your WordPress site's url and append /wp-json/wp/v2/posts



With permalinks: **http://index.local/wp-json/wp/v2/posts**
Without permalinks: **http://index.local/?rest_route=/wp/v2/posts**

Once you enter the url, hit "Send" and you'll see the response at the bottom:

Postman does a few things here that are useful for testing:

Displays the body response and formats the response automatically as JSON
Provides other views like raw (this is super helpful when using print_r to debug)
Has options to view any cookies in the request, and the headers that were sent back
Provides the status, time the response took, and the size

Sending POST requests

To send POST (or PUT and DELETE requests) from Postman to WordPress, we'll need to authenticate our requests. This is a WordPress requirement as these types of requests need to happen when logged in.

There are a couple different ways to authenticate requests from Postman to WordPress.

Passing a nonce and cookie

If you are actively working in the WordPress dashboard and need to quickly test some API methods in Postman, you can actually pass your browser's nonce and cookie values in Postman.

This requires that you perform an action that sends the API request, which you will then read from the browser's inspector tools.

From any modern browser:

Open up the browser's inspector tools
Click the Network tab
Filter to show only Fetch or XHR requests
Refresh the page (or perform an action that will cause an API request)
Click the request from the list in the inspector
Click the Headers tab
Find the request headers
copy the X-WP-Nonce header value

Then in your Postman request tab:

Click the Headers tab at the top, under the url bar
Scroll to the bottom of the list and double click the key field to make it editable
Enter X-WP-Nonce
Double click the value field next to the key field
Enter your nonce value
Enter another header and name it Cookie

Now go back to your browser's inspector tools

Find your cookies list
1. Safari: Click Storage at the top, and then Cookies in the sidebar
2. Chrome: Click Application at the top, then open the Cookies dropdown in the sidebar and select the site you are on
3. Firefox: Click Storage at the top, then open the Cookies dropdown in the sidebar and select the site you are on
Find the cookie starting with wordpress_logged_in
Copy the full cookie name and paste it into the value for the Cookie header in Postman
Add an = sign at the end
Copy the full cookie value from the browser and enter if after the = sign

Once you're done, you will see two new headers that look something like this:

X-WP-Nonce | ce243bbe44
Cookie | wordpress_logged_in_9ab7178f511b0215ddb4f12594ea7d1b=david%7C1629648436%7CKRHVjvhnwKGvUxs6lUQ6PyaPiAgi6TfwjUGwalhCQm2%7C5948f6d8ebad2bbaab3984c1876020217d6a6e9db6b90dcdda9e10c0967d6182

As you can see, it's a lot of steps. But if you are working in a system where you can't add extra authentication and need to test a POST endpoint, it can be valuable.

Basic authentication with application passwords

Using basic authentication is a much easier way to authenticate requests if you have the option. It also lets you perform more powerful testing, as you could try requests as different users with varying roles to make sure your APIs are secure.

WordPress now comes with an application password generator for users, making basic auth easy to setup:

Edit the user in WordPress you want to authenticate as
Scroll down to Application Passwords
Enter Postman in the "New Application Password Name"
Click "Add New Application Password"
The password will be shown and look something like this: jMOs od2z uGji E4Pu oYMV v1HZ
Make sure to copy the password before doing anything else. You can only see it the one time (if you screw up, revoke the password you just made and start over)

In your Postman request screen:

Click Authorization under the url field
Select Basic Auth from the type dropdown
Enter your WordPress username
Enter the password you copied

You are now setup to handle POST, PUT, and DELETE requests! To test this:

Change the request dropdown next to the url to POST
Enter your URL plus /wp-json/wp/v2/posts/<id> where <id> is a post ID
Select the Body tab under the url field
Select the raw radio option
Change the Text dropdown on the right of the radio options to be JSON
Enter: { "title": "New Title" }
Click Send

If you follow these steps, you should see something like this:

Adding authentication for multiple requests

To make authentication even easier, you should create a collection for your requests, and set the authentication globally. That way you can spin up new requests without copy and pasting your username and password every time. To do this:

Make sure your sidebar in Postman is open and set to Collections:

Click the Create Collection button in the center
Your collection will immediately be created and show authentication settings:

Select Basic Auth and perform the same steps as authenticating a single request:

Go back to your request tab and revert the Authorization settings back to "Inherit auth from parent"
Lastly, save your request and add it into the new collection

Wrap Up

You are now ready to test your WordPress REST endpoints in Postman! With these steps you can quickly test one-off APIs when you don't have access to modify users or create collections for your different WordPress installations using basic authentication.

Author

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

Handling Nonces in WordPress

David Woolf — Mon, 23 Aug 2021 10:00:00 +0000

WordPress provides an easy to use nonce system to create and verify unique hashes for certain actions. Note that WordPress uses the word nonce to refer to a security token but they aren’t true nonces. Here is how WordPress defines their use of nonce:

WordPress’s security tokens are called “nonces” (despite the above-noted differences from true nonces) because they serve much the same purpose as nonces do. They help protect against several types of attacks including CSRF, but do not protect against replay attacks because they aren’t checked for one-time use. Nonces should never be relied on for authentication, authorization, or access control. Protect your functions using current_user_can(), and always assume nonces can be compromised.

While there are plenty of times that using a nonce is not appropriate, some examples of good use cases for nonces are:

clicking a link that would alter the database
submitting a form that would alter the database
using WordPress’s REST API to perform POST, PUT, or DELETE actions

Note: a nonce is valid for 24 hours, and is not a one-time use code. This is why WordPress doesn’t consider their version true nonces.

How to create a nonce

There are a couple of ways to create nonces in WordPress, depending on where you are placing the nonce:

Generate a nonce code by itself

The most basic option is wp_create_nonce which will give you the nonce value. I find this useful for passing a nonce to a REST API endpoint as a header.

$nonce = wp_create_nonce($action); // can be a string or integer

// example:
$nonce = wp_create_nonce('trash-post-23'); 
// outputs: 5817bdf2ac

Generate a url with a nonce parameter

Next, we have wp_nonce_url which takes a base URL, the nonce action name, and the name of the parameter (defaults to _wpnonce). This will return a full URL with the nonce appended as a URL parameter

$url_with_nonce = wp_nonce_url($url, $action, $name);

// example: 
$url_with_nonce = wp_nonce_url('<https://localhost>', 'trash-post-23', '_wpnonce'); 
// outputs: <https://localhost?_wpnonce=5817bdf2ac>

Generate a hidden input with a nonce name and value

Finally, we have wp_nonce_field which is a quick way to output a hidden field with the nonce value. It also will add the referrer URL so you can verify the user came from the previous page and has a valid nonce.

wp_nonce_field($action, $name, $referer, $echo);

// example:
wp_nonce_field('trash-post-23');

// outputs: 
// <input type="hidden" id="_wpnonce" name="_wpnonce" value="5817bdf2ac">
// <input type="hidden" name="_wp_http_referer" value="/wp-admin/plugins.php?plugin_status=all&amp;paged=1&amp;s">

How to verify a nonce

When working inside the WordPress dashboard, you can quickly verify a nonce and referrer by calling check_admin_referer. By default, you need to pass in the action name. If you changed the nonce parameter name (defaults to _wpnonce), you can pass that in as a second parameter

check_admin_referer($action, $name);

// example: 
check_admin_referer('trash-post-23');

When working with async requests, you have a couple of options:

check_ajax_referer

The check_ajax_referer function will handle verification and stop processing the request

check_ajax_referer($action);

// example:
check_ajax_referer('trash-post-23');

wp_verify_nonce

The wp_verify_nonce function will handle verification but it is up to you to return an error. It’s recommended to return a 403: Forbidden error.

wp_verify_nonce($nonce, $action);

// example:
wp_verify_nonce('5817bdf2ac', 'trash-post-23'); // the nonce itself would be passed to the request and verified from the body or parameter list

Using nonces with REST API requests

If you are creating your own API requests in WordPress (for example: with fetch) and you want to submit requests using POST, PUT, or DELETE, then you will have to pass a nonce value. Fortunately, this is pretty easy if you are enqueuing your javascript files correctly.

When using wp_enqueue_script you can pass another function called wp_localize_script with any data you want to be accessible from that file:

wp_enqueue_script(
    'ndx-script',
    $path,
  [],
  '1.0.0',
  true
);

wp_localize_script(
    'ndx-script', 
    'wp_api', 
    [
        'nonce' => wp_create_nonce('wp_rest')
    ]
);

Basically, you reference the name of your enqueued script, set your own variable name to use in javascript, and then pass an array of options. This will then provide you a global object in javascript. Here is how you would use the nonce in a fetch statement

fetch(PATH, {
    headers: {
        'X-WP-Nonce': wp_api.nonce
  },
  method: 'POST',
    body: JSON.stringify({ name: value })
})
.then(response => response.json())
.then(response => {
    // do something here
})

The only important part of this is the headers option in the second parameter of the fetch statement, passing the nonce. Custom headers always start with X and then WP-Nonce is defined by WordPress itself and what they’ll look for.

What’s great about this pattern is that you don’t need to verify the nonce in your rest endpoint. The system takes care of that for you and will return a 403: Forbidden error if you try to submit something without a nonce

Note: publicly consumable API endpoints do not require this which is why you can fetch a list of posts right from your browser in the URL field.

Wrap up (and a note on security)

Once again, it’s important to note that nonces should not be used in place of proper authentication. They are simply an extra check to prevent authenticated users from performing an action they didn’t intend to.

With the REST API especially, the nonce example here is only for requests sent while a user is logged in, and your endpoints should also use the permissions callback to check if the current user can perform the intended action.

I would also recommend you use the nonce functions that take care of some of the heavy lifting for you (like creating and verifying hidden fields with the nonce value).

Author

.ltag__user__id__628430 .follow-action-button { background-color: #000000 !important; color: #ffffff !important; border-color: #000000 !important; }

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf

Function breakdown: rest_ensure_response

David Woolf — Thu, 19 Aug 2021 16:33:58 +0000

When making your own routes with the WordPress REST API, you have to return a valid REST object. WordPress provides a couple of ways to do this, including the rest_ensure_response function. When working with REST APIs in Javascript you will see this a lot:

fetch('rest-endpoint')
.then(response => response.json())
.then(data => // ...do something with the data here)

The first method on the fetch function is passed the response object, which then returns the request's body. The second method is then passed that request body as JSON.

This pattern is possible because the data from the API is returned properly. Read on to see how the rest_ensure_response function works and how you can use it in your own routes.

Function definition

The WordPress code reference describes rest_ensure_response as:

[rest_ensure_response] implements WP_REST_Response, allowing usage of set_status/header/etc without needing to double-check the object. Will also allow WP_Error to indicate error responses, so users should immediately check for this value.

The documentation states that the function takes one parameter, which can be multiple types:

// you normally return the result from a rest route
return rest_ensure_response(
    // return one of:
    // WP_REST_Response
    // WP_HTTP_Response
  // WP_Error
    // ?... (mixed content)
)

You can return a WP_REST_Response class, WP_HTTP_Response class, WP_Error class, or mixed content. Let's review the function definition, see how it works, and what it returns.

Note: mixed content just refers to different types of data: arrays, object, strings, booleans, integers, etc.

Return value of the function

Here is the function definition:

// location: wp-includes/rest-api.php
function rest_ensure_response( $response ) {
    if ( is_wp_error( $response ) ) {
        return $response;
    }

    if ( $response instanceof WP_REST_Response ) {
        return $response;
    }

  // While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide
  // all the required methods used in WP_REST_Server::dispatch().
    if ( $response instanceof WP_HTTP_Response ) {
        return new WP_REST_Response(
            $response->get_data(),
            $response->get_status(),
            $response->get_headers()
        );
    }

    return new WP_REST_Response( $response );
}

First, the function checks if the passed in value $response is a WP_Error and if so, it returns it immediately.

Next, it checks if the passed-in value is a WP_REST_Response instance and if so, returns it directly. Otherwise, if the value is a WP_HTTP_Response instance, it returns it as a WP_REST_Response and passes the data, status, and headers to the class.

If all else fails, the function defaults to returning the value as a WP_REST_Response instance. All of this is to say, it's either going to return a WP_Error or WP_Rest_Response instance.

What you'll normally pass to the function (aka: mixed content)

In your own code, you'll probably be passing in mixed content (your data) to rest_ensure_response. End users are usually returning rest_ensure_response from a custom register_rest_route and passing back either an error or valid data.

Here's a simple example of rest_ensure_response in a custom route:

function callback_for_custom_rest_route($request) {
    $data = isset($request['name']) ? $request['name'] : new WP_Error('missing_name', 'please provide your name');

    // if name is set, return a 200 OK with the string value passed in for name
    // if name is not set, return a 500 Internal Server Error with error information defined above
    return rest_ensure_response($data);
}

And that's all you need to use rest_ensure_response!

How to get started with WordPress Hooks in Javascript

David Woolf — Tue, 17 Aug 2021 15:54:33 +0000

WordPress has provided hooks in PHP for years and they recently released a version for Javascript. Hooks allow different parts of your code to augment values or perform additional actions. When referring to actions and filters, we'll be using the term "hooks" to discuss both. If you see the words "action" or "filter", assume we're discussing functionality that only relates to only that hook.

How to start using WordPress hooks in Javascript

Before handing WordPress hooks in Javascript, make sure you are coding in a JS file that has access to the global wp javascript variable, or that you are using the @wordpress/hooks npm package

This article will be using the wp global variables hook endpoints for coding examples. If you are enqueuing your javascript correctly in WordPress, you should already have access to this variable. You can confirm this by doing console.log(wp.hooks)

Adding your own hooks

Adding actions and filters in Javascript is similar to PHP:

// actions
wp.hooks.addAction('hookName', 'namespace', callback, priority)

// filters
wp.hooks.addFilter('hookName', 'namespace', callback, priority)

The parameters for both hook types are:

hookName: the name of your action or filter, which you'll use to call the hook
namespace: a custom namespace (for example: your product name).
callback: the function that will execute your hook
priority: the order in which your hook fires

I'm not sure why the namespace parameter exists because you don't use it when calling a hook (although you do when removing one). To prevent duplicate hook names, I would recommend adding a namespace to your hook name as well.

Applying hooks in your code

Just like with PHP, you have access to a couple of functions to call your filters and actions:

// actions
wp.hooks.doAction('hookName', ..args)

// filters
wp.hooks.applyFilters('hookName', 'content', ...args)

Notice how we don't refer to the namespace here, which is why I recommend adding one to your hook name.

Reminder: filters take a default value before the args list, and should return a value to a variable. Actions should execute code and not return anything.

With these four API methods, you can implement a Javascript version of WordPress's hooks system.

Troubleshooting when hooks don't fire in the correct order

An issue I ran into the first time I tried to use the wp.hooks.addFilter method was inconsistent filter execution.

I was trying to pass a string through two addFilter calls in separate plugins and I wanted the end value to include any modifications in each callback. Here is how I enqueued my javascript files in PHP (split between two plugin.php files):

// first plugin
wp_enqueue_script(
    'ndx-first-plugin-script', 
    plugin_dir_url(__FILE__) . 'dist/js/first.js', 
    [], 
    '1.0.0', 
    true
);

// second plugin
wp_enqueue_script(
    'ndx-second-plugin-script',
     plugin_dir_url(__FILE__) . 'dist/js/second.js',
     [],
     '1.0.0',
     true
);

In my first.js file I created a filter that would return "I am the beginning" prepended to a passed in value:

// ndx-first-plugin-script (first.js)
wp.hooks.addFilter(
    "ndx_change_string",
    "index",
    (value) => {
        return `I am the beginning. ${value}`
    },
    10
)

In my second.js file, I added the same filter hook with a higher (read: lesser) priority and appended "I am the end" to the passed-in value:

// ndx-second-plugin-script (second.js)
wp.hooks.addFilter(
    "ndx_change_string",
    "index",
    (value) => {
        return `${value} I am the end.`
    },
    20
)

console.log(wp.hooks.applyFilters("ndx_change_string", ""))

Because my apply calls passed in empty strings I expected the result: "I am the beginning. I am the end." but what I got was "I am the end."

Unfortunately, my second plugin's javascript loads first and doesn't see the first plugin's filter value (this can happen in PHP too, by the way). You will generally use filters to augment a standalone value, but it's also common to use them to add and remove items from arrays so sometimes the order is important.

There are a couple of ways to solve this problem:

Ensure the plugin where you plan to call applyFilters is enqueued as a dependency in your other scripts:

// second plugin
wp_enqueue_script(
    'ndx-second-plugin-script',
     plugin_dir_url(__FILE__) . 'dist/js/second.js',
    ['ndx-first-plugin-script'], // add your first plugin script as a required dependency
    '1.0.0',
    true
);

Or utilize the built-in hookAdded method to call additional filters after the first one is created:

wp.hooks.addAction(
    "hookAdded",
    "core/i18n",
    (name, functionName, callback, priority) => {
        if(name == "ndx_change_string" && priority == 10) {
               // add additional filters here after the first one fires
        }
    },
    10
)

Note that the hookAdded method can be fragile and buggy and it would be very easy to get stuck in an infinite loop if two addFilter calls had a priority of 10.

WordPress REST API: Delete method returns an error

David Woolf — Mon, 26 Apr 2021 16:31:58 +0000

WordPress provides GET, POST, PUT,andDELETE methods for a variety of content. In Index, we use the /post/<id> endpoint with the DELETE method to trash posts when a user clicks delete. This seemed pretty straightforward, but during testing we ran into a problem: our posts were not being deleted.

The problem we ran into with DELETE

Every time we introduce a new feature to Index, or install it on a new machine, we do a few commands to make sure the core experience of the plugin is intact:

Select and edit posts
Select and trash posts
Permanently Delete some trashed posts
Restore some trashed posts
Attempt all the above with a user role that can’t do it

Around December of last year, we started using Local for all local WordPress development. When we switched, we did the above steps. Everything worked great, except when we tried to trash posts. No matter what post we tried to delete, we would receive an unauthorized error, and the post was never removed. We double checked that our role should be able to delete posts, and once we confirmed that, we opened up the Postman app and tested some other api requests that require authentication. All of those were working, so why couldn’t we delete a post?

Next, we tried was removing a post from the Gutenberg editor. That worked, so clearly there wasn’t some unfixable issue with the web server. So we opened up our web inspector, reviewed the network requests and discovered that WordPress was using the same post/<id> endpoint, but it was using POST instead of DELETE for the method.

The solution to deleting posts using the WordPress API

After some digging, we found that Local uses nginx as a web server and only has the GET and POST methods enabled for api requests (others like PUT and DELETE are not enabled). The solution ended up being simple, but might not be obvious to anyone that doesn’t work with APIs every day.

Send the request with the method set to POST and add an additional header to your fetch statement:

'X-HTTP-Method-Override': 'DELETE'

Doing this ensures broader support for different hosting environments that may not have methods other than GET and POST enabled. Nothing has to happen on the PHP side, and if you are making your own endpoints with register_rest_route, you can keep setting up your methods per the WordPress documentation website.

Author

.ltag__user__id__628430 .follow-action-button { background-color: #000000 !important; color: #ffffff !important; border-color: #000000 !important; }

David WoolfFollow

Designer and developer. Follow me on twitter: https://twitter.com/wwuulf