oEmbed Updates

Several years ago, WordPress.com introduced oEmbed provider support to allow posts on WordPress.com-hosted blogs to be embedded anywhere that supported oEmbed. WordPress 4.4, due out in December, will bring oEmbed provider support to the wider WordPress world.

One week from today, on October 2, the WordPress.com team will be switching our oEmbed format to match the global WordPress format. The oEmbed spec allows for arbitrary changes in the HTML being returned, but since this is a significant change we wanted to give everyone ample lead time.

Where the current HTML format included some post content and a bit of markup, the new format is more in the style of Facebook or Twitter embeds — the content is now inside of an iframe, with a small bit of JavaScript.

We understand that not everyone is comfortable with embedding arbitrary scripts on their page. If you wish, you may strip the script tag and provide the same functionality using the script from the development plugin. If you choose this method, please keep in mind that this script is still under development, and will likely change between now and WordPress 4.4’s release.

In order to test the new embeds, simply add the query string ?newembed=true to the URL of any post hosted on WordPress.com, like so. Similarly, you can get the output from our oEmbed endpoint by adding &newembed=true to the end of the request. We’re still working on adding support for this new style of embed to the WordPress.com post editor, but you can test it on your own WordPress install using the feature plugin.

If you run into any issues or have any questions, please post them in the comments below!

Update: September 25, 2015 16:00 UTC — We are temporarily reverting this change. Please see the comment below. We’ll update this post when the new oEmbed is re-enabled.

A more secure REST API

Because privacy and security are important to users across the internet, many services have begun to encrypt the connection between a user’s browser and their servers. The use of SSL (or TLS) largely eliminates the likelihood that a “man-in-the-middle” is able to monitor a user’s activities on the web. To this end, WordPress.com is joining the likes of Google and Facebook in encrypting all of the traffic sent across our network. We are currently in the process of forcing many of our services to be accessible through HTTPS exclusively.

It was previously possible to access the WordPress.com/Jetpack JSON API through HTTP only for unauthenticated requests. As part of the SSL transition, all public-api.wordpress.com endpoints are now accessible via HTTPS only. Any requests made to the HTTP version of the URL will now 301 redirect to the HTTPS version.

What does this mean for you?

For the majority of our API consumers, this won’t require any change as you are likely already using the HTTPS URLs with authenticated endpoints. If you are not, now is the time to update your API calls to the secure URLs.

By making this change, we’re helping make the web a more secure place for our users.

As always, If you have any questions about the API, don’t hesitate to comment below or reach out to us via our developer contact form.

Version 1.1 of the WordPress.com REST API

Today, we’ve launched version 1.1 of the WordPress.com REST API. In recent weeks, we’ve been hard at work launching new features on WordPress.com, and many of these changes are powered by our REST API. When we started working on the upgrades to stats and post management, we quickly realized that the existing endpoints didn’t have all the power we needed to provide the best experience. In order to add the functionality we needed to the API without breaking existing implementations, we decided to version our API.

What does this mean for you?

If you’re already implementing version 1 of the API, you’ll be able to continue using those endpoints without changing your code for the foreseeable future. Version 1 of the API is now deprecated, so any new development you do should be against 1.1. We currently have no plans to disable version 1 of the REST API — should we ever decide to do so, we’ll give you plenty of advanced notice.

Media Endpoints

  • Upload support for all file types. If you can you upload it though the media explorer, you can upload it with the API. PDFs, Docs, Powerpoints, Audio files, and Videos (Jetpack & .com blogs with VideoPress) are all supported.
  • Better error handling. If you upload multiple files and some fail, it’s easier to pull those out and retry.
  • Improved consistency with other endpoints and cleaned up response parameters.
  • When uploading files, you can now pass attributes like name and description without needing to do a second call to the update endpoint.
  • Bonus: The /sites/$site/ endpoint now returns a list of allowed file types.

Stats Endpoints

  • Support for pulling back stats over multiple days without those stats being grouped into a single result.
  • New stats detailing the top comment authors on your site, as well as the posts that have received the most comments.
  • In addition to chart data for views and visitors: chartable data about likes and comments.
  • Keep on track with your posting goals. The new streak endpoint contains the data to help motivate you to post more often.

We’re looking forward to seeing what you build using version 1.1. Take a look at the REST API documentation to get started. If you have any questions about the API, don’t hesitate to comment below or reach out to us via our developer contact form.

On API Correctness

Developing APIs is hard.

You pour your blood, sweat, and tears into this interface that bares the soul of your company and of your product to the world. The machinery under the hood, though, is often a lot less polished than the fancy paint job would lead the rest of the world to believe. You have to be careful, then, not to inflict your own rough edges on the people you expect to be consuming your API because…

Using APIs is hard.

As an app developer you’re trying to take someone else’s product and somehow integrate it into whatever vision you have in your head. Whether it’s simply getting a list of things from another service (such as embedding a reading list) or wrapping your entire product around another product (using Amazon S3 as your primary binary storage mechanism, for example), you have a lot of things to reconcile.

You have your own programming language (or languages) that you’re using. There’s the use case you have in mind, and the ones the remote devs had in mind for the API. There’s the programming language they used to create the API (and that they used to test it). Finally, don’t forget the encoding or representation of the data — and its limitations. Reconciling all of the slight (or major) differences between these elements is a real challenge sometimes. Despite years of attempts at best practices and industry standards, things just don’t always fit together like we pretend that they will.

As a developer providing an API it’s important to remember three things. There are obviously many other things to consider, but these three things are more universal than most.

#1 You want people to use your API.

Unless you’re developing a completely internal API, you’re hoping that the world sees your API as something amazing, and that your functionality starts popping up in other magical places without any further effort on your part.

#2 You have no control over what tools others are using.

Are you using a language that has little or no variable type enforcement? Some people aren’t. Some of those people still want to use your product. Did you come up with your own way of doing things with custom code instead of using widely-adopted industry standards (which, being widely deployed, come with battle-tested libraries in many languages)? Did that cause you to release a client in your own language (how about Clojure, how about Erlang, how about C++, how about Perl, how about…)?

#3 Your API is a promise.

It’s easy to forget (especially for those of us who spend our time in a forgiving language such as PHP or Python) that the API we provide is a promise to the rest of the world. What it promises is this: “When you provide me with ${this} I will provide you with ${that}”.

The super-important (and insidiously non-obvious) thing about this is that if you do not provide a written promise (in the form of your API’s documentation), then the behavior of your API becomes the implicit promise.

The most important thing to note here is that when your documentation is wrong, the promise of your actual behavior wins every single time.

Keep your promises

When your promises don’t match your actual results things get hairy.

Let’s take a look at a completely hypothetical situation.

  1. You have an API that is documented to return a json object with a success member which should be a boolean value.
  2. You have a case (maybe all cases) where success is actually rendered as an integer (0 for false, 1 for true).
  3. John has an app written in a strongly-typed language that works around this by defining success as an integer type instead of a boolean type. Because John was busy, he never got around to letting you know. Or maybe John never knew because he simply inspected your API and worked backwards from the responses that you gave. Now John’s app has 100k users depending on this functionality.
  4. Mary is writing an app, and because Mary doesn’t like to play fast and loose (and she doesn’t want her app to break later on) she submits an issue pointing out that you are returning the wrong type.

At this point you are trapped. The existing user base (and by extension their user base) is committed to integers. And you only have four options.

  1. You can cripple an existing and deployed application enjoyed by 100k users.
  2. You can version your API — an entire new version to correct what should be a boolean value.
  3. You can work with John to roll out a new version of the app which can handle both (but maybe his app is in the iOS app store, and getting everyone to update is impossible, takes a long time, and/or would require a lengthy, and potentially costly, review process by yet another party).
  4. You make a really sad face and change your promise — to reflect that you are going to do what is actually the less correct thing, forever.

Because you wrote an API whose promise was wrong, or whose promise was missing, you have painted yourself into a very undesirable corner. You’re now in a place where doing the right thing for the right reasons is the wrong move.

So do yourself, and everyone else, one of two favors — depending on the position in which you find yourself.

If you’re producing an API, take extra care to make sure that your results match your documentation (and you need to have documentation).

If you’re consuming an API, don’t be like John. Don’t work backwards from the data — work forwards from the docs. And if the docs are wrong you should submit a ticket and wait for it to be fixed (or at the very, very least, make sure your workaround deals with both the documented expectation and the actual incorrect return value).

In conclusion

Just like a child, it takes a village to raise a good, decent, hard working API.

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:


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.


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.

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.