WordPress REST API on WordPress.com

As you might know if you follow WordPress developer news, the WordPress REST API content endpoints are slated to be merged into WordPress core in the upcoming 4.7 release. These endpoints cover basic WordPress features (posts, pages, custom post types, revisions, media, comments, taxonomies, users, and settings). While they have also been available via the WP REST API plugin for some time, this is the latest step in a multi-year project to bring a modern, RESTful API to all WordPress installations.

We are pleased to announce that WordPress.com is now running the WordPress REST infrastructure alongside our pre-existing v1 API. Additionally, we have made the new content endpoints available now so that developers can try them out, provide feedback and drive wider adoption of the new API.

The success metrics for this feature, detailed here, focus on increasing utilization of the new API in plugins, themes, third-party clients and within WordPress core itself. This new API represents the future of WordPress and WordPress.com, and we want to make it as solid as we can. We encourage all WordPress developers to take it for a spin and let us know what you think!

Using the New API

The WordPress REST API is available on WordPress.com with the following base URL: https://public-api.wordpress.com/wp/v2/. This new API is backwards-incompatible with the v1 API, which we have no plans to deprecate at this time.

Going forward, we encourage developers to write new code against the v2 API whenever possible. This has the added benefit of making your applications able to run against both WordPress.com and self-hosted WordPress sites.

Documentation for the WordPress REST API and its endpoints can be found at http://v2.wp-api.org/.  Our installation of the API uses the same OAuth2 authentication tokens as our version 1 API.

To make testing and exploration easier, we’ve also updated our API console to support both versions of our API. You can switch API versions using the dropdown toggle in the upper left:

wpcom-wp-rest-api-1

 

Once you’ve selected the WP REST API, you can view and select endpoints and make authenticated requests just as in the previous version:

wpcom-wp-rest-api-2-cropped

Caveats

For self-hosted sites running the Jetpack plugin, we expect read requests to work (but you must be running at least Jetpack version 4.3.2).  Write requests to Jetpack sites do not work yet, since this will require the site to be running the content endpoints and a future version of the Jetpack plugin that supports them.

In addition, a few endpoints are restricted or disabled on WordPress.com, generally for parity with our v1 API. A few examples:

  • Listing and retrieving media items requires authentication
  • Listing and retrieving user info requires authentication
  • Endpoints to create/edit/delete users are disabled
  • Updating the email and URL settings via the settings endpoint is disabled

Examples

Here are some examples that could serve as a starting point. If you build your own, please share it in the comments!

How to Provide Feedback

REST Development Console — now open source!

For developers working with the REST API, the browser-based API console is an essential debugging tool. It allows you to test your API queries and interactively explore the results (or errors) that the API returns.

REST API console - exploring results

It also puts the documentation at your fingertips and allows you to build a custom query right from any method’s description.

REST API console - building a query

Like the REST API itself, this tool works for any blog on WordPress.com and for any self-hosted WordPress install using Jetpack.

With the addition of implicit OAuth, we’ve released an open-source version of the API console that you can run yourself.

First, you’ll want to create a WordPress.com application (or modify an existing one) and make sure to set the Javascript Origins option. This should be the fully-qualified URL (including http:// or https:// ) of the site you’ll be running the API console on. To run it locally, just use “http://localhost”.

REST API console - JS origins setting

Then, just head on over to the GitHub repository, clone your own copy, and put your application’s info in the file config.json.

Screen Shot 2014-06-10 at 5.23.59 PM

When you’re running the console locally, you can authenticate by clicking on the box in the lower-right corner.

dev console - auth button

Once you’re linked to a blog, the blog’s ID will be shown in the lower right. You can click on it to change which blog you’re working with.

Important note: When you’ve connected to a blog, the console is hooked up to the live database — any changes you make will be reflected on that blog! You might want to create a test blog if you’re planning to make any requests that will modify content.

The REST API console is located at https://developer.wordpress.com/console/.

If you’re using the API, we’d love to hear what you think! Have you used the development console? What’s great (or not so great) about it?