Improved REST API Support for Custom Taxonomies

The WordPress.com REST API has always enabled developers to manage categories and tags for the posts on a site. Until now, however, if a site had enabled any custom post types with custom taxonomies, developers were out of luck if they had hoped to manage custom terms using the REST API.

We’re happy to announce that this is no longer the case, with improved support for custom taxonomies. This includes a handful of new endpoints and enhancements to existing endpoints.

Specifically, you can now…

Note that taxonomies and terms are only included in a response if the taxonomy is registered as public or if the authorization token sent with the request has the proper capabilities for viewing or managing that taxonomy. Refer to the register_taxonomy function documentation for more information.

As an example, if a Jetpack site supported a custom book post type with a genre taxonomy, I could create a new book by issuing the following cURL command:

curl \
 -H 'authorization: Bearer YOUR_API_TOKEN' \
 --data-urlencode 'title=Sample Book' \
 --data-urlencode 'type=book' \
 --data-urlencode 'terms[genre][]=Fiction' \
 'https://public-api.wordpress.com/rest/v1.2/sites/example.com/posts/new/'

If you’re new to working with the WordPress.com REST API, we recommend you head on over to our Getting Started with the API guide to learn more.

OAuth2 Global Scope Tokens

The WordPress.com REST API has enabled developers to create rich applications to interact with blogs hosted on WordPress.com or hosted elsewhere when used with the Jetpack plugin. Until now, it’s only been possible to request an authorization token for a single blog at a time, but we’re happy to announce that this limitation has been lifted. Starting today, you can request access to all sites to which a user has administrative access by using the global scope option with our existing OAuth2 authentication process.

To use the new global scope, redirect your users to the OAuth2 authorization endpoint below to request access to all of the user’s sites:

https://public-api.wordpress.com/oauth2/authorize?client_id=your_client_id&redirect_uri=your_url&response_type=code&scope=global

The user will be presented with an improved authorization screen to more clearly reflect the permissions being granted to your application, as seen in the screenshot below.

global_authorization

You can learn more about the OAuth2 authentication flow at our detailed support article.

If the user chooses to grant you access to all of their sites, you will receive a token which includes a scope value of “global”.

{
    "access_token": "YOUR_API_TOKEN",
    "token_type": "bearer",
    "scope": "global",
    "blog_id": 0,
    "blog_url": null
}

Once you’ve received your access token, you can view all of the user’s sites by making a request to the /me/sites endpoint.

It’s important to consider whether or not your application needs access to all of a user’s sites or if working with a single blog at a time is sufficient. As you might expect, users will tend to be more cautious when granting access to all of their sites to an unfamiliar application.

We hope that this new feature will enable you to build more powerful applications where it’s useful to manage more than one site to which a user has access. If you have any questions, leave a comment below or use our contact form to reach us directly.