Neu! veranstaltung Blogs Templates User

Welcome to the Tumblr API, v2!

Want to know what’s changed and why? Read on. Just want to dive in? Head on over to the API documentation, sign up for a key, and get hacking!

New Features

Features on Tumblr evolve rapidly. With the API, we have not attempted to provide complete feature parity with the website. Instead, we’ve focused on those features which have become widely adopted and thus core to the experience.

Just a few examples of features now exposed in the API:

• Followers: Once authorized by a user, an application can access the list of blogs a user is following.
• Photosets: Upload multiple photos to create Photoset posts.
• Blog Info: Pull a blog’s description, avatar, and last-update time.

Consolidation and Clarification

The previous version of the API made distinctions between read and write operations and pushed different activity to different domains (www.tumblr.com and the blog subdomain). To make developers’ lives easier, we have consolidated all API access to api.tumblr.com and made visible our two major concepts in the URI: /blog and /user. By exposing developers to our core organizing principles, we hope they can have clearer mental model of how the different aspects of Tumblr fit together. In addition, having all API access consolidated under one domain allows us to cleverly measure and balance traffic using DNS and other mechanisms.

Favoring Experimentation over Documentation

Developers should be able to easily discover and experiment with an API without having to dig through piles of documentation. The URLs should follow a pattern, be guessable, and the responses should be self-describing. While I think we’ve come close to reaching our goal, there will probably come a time when you’ll need exact descriptions for thing like what the value of “updated” means in the followers call or what fields need to be passed back when reblogging a post. We’ve rewritten our documentation to provide a concise explanation of each of these more finicky details in an easily scannable format.

Names

Strict REST is great dogma that’s difficult to practice. Instead of attempting to be completely “RESTful,” we created simple URLs that enable composability for the average human.

For example, developers commonly need to pull a blog’s avatar. Knowing just the URL of your favorite blog makes this as simple as http://api.tumblr.com/v2/blog/derekg.org/avatar, which returns a sane default size. If you want something bigger, append the size and you’ve got it: http://api.tumblr.com/v2/blog/derekg.org/avatar/512

Result Formatting

In the first version of our API, data was available in XML, with JSON support added largely as an afterthought. XML as a means for delivering developer-friendly data hasn’t aged well. Seeing the growing inclination of developers and API makers alike towards JSON, we’ve decided to eliminate XML support and put the energy spent there into getting our JSON implementation just right.

Tracking and Authorization

Protecting our community’s security and privacy is top priority, which was not reflected well by the fact that our earlier API allows developers to store passwords on behalf of users. With the implementation of the new API, OAuth 1.0a is now required to access all non-public data. While OAuth 1.0a has some learning curve, we feel it strikes a reasonable balance between user security and developer productivity. OAuth 2 looks promising, and we hope to make that available at some point in the future.

We’ve also added a requirement for non-authenticated reads to provide an API key. This helps us better measure API usage without relying on IP addresses alone to tell us how and by whom the API is being used. This will permit us not only to more readily identify and eliminate the rare bad actors, but better understand the needs and use cases of legitimate apps. Hat tip to our friends at SoundCloud, who inspired us to re-use the OAuth 1.0a consumer key as our non-authenticated API key.