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…

• Retrieve a list of terms for a site
• Retrieve a single term for a site
• Create a new term
• Update an existing term
• Delete a term
• List taxonomies associated with a post type
• Retrieve a post including terms for all public taxonomies
• Create or update a post including terms for any taxonomy
• List posts filtered by a custom taxonomy term (available now for WordPress.com sites and in a future Jetpack release)

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.

Custom post type and metadata support in the REST API

We’ve recently made some updates to the REST API which is available here on WordPress.com and for any Jetpack-enabled site that has the REST API module activated. The API now has full read and write support for custom post types and post metadata.

You can specify a post’s post type when you create or edit it. If you’re fetching a single post, you will receive its post type in the response. Of course, you can also specify a post type when fetching a series of posts. In all cases the parameter to use or look out for is type.

You can also query posts by metadata using the new meta_key and meta_value parameters. You can add, update, delete or retrieve a post’s metadata when creating, editing or getting a single post, using the new metadata parameter which accepts an array of metadata keys, ids, previous_values, values and operations, based on the operation you are trying to perform.

In order to enable your custom post types to work with the REST API on your Jetpack enabled sites, you will need to whitelist them using the new rest_api_allowed_post_types filter available in Jetpack, which is a simple array of the post type names that should be allowed to work with the API.

All metadata keys can be accessed and edited by users with the edit_post_meta (used for editing and viewing), add_post_meta and delete_post_meta capabilities as appropriate for each operation. We’ve also added a filter rest_api_allowed_public_metadata that allows you to specifically whitelist certain metadata keys to be accessed (but not modified) by any user (even anonymous).

Here’s a quick rundown. If the user performing the request is unauthenticated, they will not be able to add, edit or delete any metadata; they will only be able to read specifically whitelisted metadata keys.

If the user performing the request is authenticated and has the above listed capabilities, they will be able to read, add, edit or delete any metadata, even if it is not whitelisted.

In order to make it easier for you to add support for custom post types and metadata in your own plugins and themes, we’ve also added a third filter jetpack_rest_api_compat in the main Jetpack file, which allows you to load additional files where you can then add all of your REST API compatibility code, using the filters above.

Because we love bbPress, we’ve bundled support for bbPress and the REST API directly into Jetpack, so that you can read, write and edit bbPress forums, topics and replies right out of the box. You can also use this file as an example on how to bundle support in your own plugins or themes.

Check out our documentation, create an app, and get started today!

Let us know if you have any questions in the comments below.