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?

Meet Sulfur — a Media Manager App Built in JavaScript

Since Automattic is a distributed company and a lot of us work from home, we hold meetups to get face-to-face interaction. The whole company meets up once a year and individual teams get together more often. One component of those meetups is a “meetup project” that we all work on together.

The team I lead — “Team I/O*” — just finished a lovely week in Reykjavik, Iceland. Our team is responsible for partnerships and our APIs.

We spent the first day releasing better JavaScript support for our APIs. After that we decided to make an example app, mainly focusing on the new CORS support and implicit OAuth system.

We decided to build a media manager purely in the browser. We picked a codename and Sulfur was born.

Update: Check out the live demo!

Screen Shot 2014-05-20 at 5.18.13 PM

Sulfur is an app built using Backbone, Underscore.js, Plupload, jQuery, MomentJS, Bootstrap, RequireJS, and the WordPress.com JSON REST API.

It shows how you can use Implicit OAuth to do authentication without a server component. It also provides examples for using the API with Backbone and third party libraries like plupload for uploading media.

Sulfur allows you to upload images, view your entire media library contents, view meta data, and delete images. All the code is open source. Check out Sulfur on GitHub.

We learned a lot while building the app and hope to use that knowledge to improve our APIs both for internal and external use.

Screen Shot 2014-05-20 at 9.11.02 PM

Let us know what you think in the comments!

*Named after one of the moons of Jupiter and our love of APIs (input/output)

Platform Updates: Posting Endpoints

We have made a few recent additions to our posting APIs that allow more control when creating posts.

You can now

  • Set a custom slug for the post permalink using the slug parameter.
  • Disable or enable the publicizing of posts, or only publicize to certain services (Twitter, Facebook, etc) using the publicize parameter.
  • Pass a custom message to the above publicize services using the publicize_message parameter.
  • Set the status of a post as “pending review” by passing pending to the status parameter.

When getting a post you can now

  • Find the featured image for a post using featured_image which will return a URL.

Using the REST API with WordPress.org self-hosted sites via Jetpack

As of Jetpack 1.9, the WordPress.com REST API can now access self-hosted WordPress blogs with the Jetpack plugin installed.

Instead of just building for the WordPress.com platform, you can build awesome applications that interact with WordPress in general. Any applications built using the API for WordPress.com will automatically work with Jetpack-enabled sites running Jetpack 1.9 or higher.

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

WordPress.com for Windows Metro and the REST API

WordPress.com for Windows Metro

When we were starting work on the WordPress.com for Windows Metro app, we decided to build it entirely with the brand new WordPress.com REST API. The API gave us everything we needed to create a full-featured application that includes reading blogs, social features (post likes, reblogs), and creating new posts. Let’s take a look at a few code samples to see how we leveraged the API:

*note* All sample code is a condensed version of code from the Metro App. You can view the full source of the app at our trac site.

Creating a New Post

Once a user has authorized the app using OAuth (more info here), they can create new posts in the app. The /posts/new endpoint makes it very easy to create a new post via an XMLHttpRequest (xhr):


function publishPost() {
var title = "I Need a Good REST";
var content = "That's probably the corniest blog title ever created...";

var data = new FormData();

data.append('title', title);
data.append('content', content);
data.append('format', 'standard');

//note: blogID and users_access_token are received from the OAuth API
var url = 'https://public-api.wordpress.com/rest/v1/sites/' + blogID + '/posts/new';
 WinJS.xhr({
     type: 'POST',
     url: url,
     headers: { 'Authorization': 'Bearer ' + users_access_token },
     data: data
   }).then(function (result) {
     var resultData = JSON.parse(result.responseText);
  if (resultData.ID) {
    //post published!
  }
  else {
    //post publish failed
  }
}

Liking a Post

The Windows Metro app takes full advantage of the social features on WordPress.com, including likes, blog follows, and reblogs. Let’s take a look at using the /likes endpoint so that we can like a post through the API:


var curText = m.target.innerText,
likeButton = document.getElementById('like');
//just an example post_id
var post_id = 123;
//note: blogID and users_access_token are received from the OAuth API
if (curText == 'Like') {
   label.innerText = 'Liking...';
   url = 'https://public-api.wordpress.com/rest/v1/sites/' + blogID + '/posts/' + post_id + '/likes/new';
 } else {
   label.innerText = 'Unliking...';
   url = 'https://public-api.wordpress.com/rest/v1/sites/' + blogID + '/posts/' + post_id + '/likes/mine/delete';
 }

WinJS.xhr({
   type: 'POST',
   url: url,
   headers: { 'Authorization': 'Bearer ' + users_access_token }
 }).then(function (result) {
   //like operation successful!
 }, function (result) {
   //error
 });

You can see how we can also remove the like on the post by simply changing the endpoint on the post to /likes/mine/delete.

Conclusion

These examples are a small drop in the bucket of what you can do with the WordPress.com REST API. For a full list of the endpoints that are available, check out the documentation.

We’d love to hear how you are using the API in your applications! Drop us a note at our contact form to get in touch with the developer.wordpress.com team.

Explore the REST API

I have had the pleasure of working with the WordPress.com REST API over the past few weeks and am very excited to start “dogfooding” this resource everywhere I can.

One cool feature is that all the endpoints are self-documenting. In fact, the documentation for the REST API is built by the API itself! With this information we were able to build a console to help debug and explore the various resources that are now available through the new API. So let me introduce you to the new REST console for WordPress.com.

Screenshot of the REST API Explorer

A word of caution: the console is only available when you are logged into WordPress.com and is hooked up to the live system, so be careful with your POST requests!

At its simplest you can supply the method, path, query, and body for the resource you wish to examine (it’s pre-populated with /me). Press “Submit” to see the response status for your request and an expandable JSON object that you can explore. All links listed under meta are active, so click one to make another request.

To get a better idea of what kind of parameters a request can take, select it under the “Reference” section. It will then provide an interface with some contextual help to let you know which path, query, and body parameters it accepts, what each of those parameters are for, and a field for you to provide the value.

Example of the contextual help for the "number" parameter for a request query variable.

You can try out the console by visiting http://developer.wordpress.com/console or by expanding the “Developer Console” pane at the bottom of any of the REST Documentation pages.

So go explore the new REST API and build something awesome!