This was a session by Alex Payne (Twitter) and Michal Migurski (Stamen Design, who did the Digg Labs apps) on their experiences designing, implementing, and scaling APIs. My rough notes are after the jump.

Design Your API: Learnings from Twitter and Stamen
Development, room 2003, Wed 2:40 PM
Alex Payne (Twitter), Michal Migurski (Stamen Design)

Alex Payne (Twitter)

Documentation: Don’t sweat the tiny details, at first. What’s most important is that developers can get started quickly. Provide simple examples and tutorials that are closely linked to the API docs.

Support: Be available to answer questions. Twitter found Google Groups to be a great forum for this kind of thing. Delegate to power users; they’re gold.

Scale: You might not have to watch out for this immediately, but Twitter found that not long after releasing its API, API traffic exceeded web traffic.

Secure: If you have the resources, conduct an independent audit. Prepare for the inevitable leak of personal information, PR-wise.

What Twitter did Wrong:

• Didn’t start with api.twitter.com, which made traffic shaping and caching a pain in the ass. Switching it, now, will be a pain in the ass.
• Likewise, didn’t version the API. On the other hand, not versioning has forced the developer community to be very involved. This is maybe a good initial tact, but quickly falls apart.
• Didn’t make life easier for Flash developers. Flash developers really think visually, making sexier apps than are available in the DOM world. Keep them in mind. FLash is slow with large chunks of XML; use smaller chunks. There are also cross-domain restrictions with Flash that can be addressed by the XML format. Provide and Actionscript library, too. This may occlude some of the functionality, but reduces the pain-in-the-butt factor for Flash developers who just want to get started (not bad advice for the web side, either…)
• Didn’t automate to make life easier for us.

New In The Twitter API:

• Rudimentary Geolocation
• More consistency between methods. Conventions are good; don’t make your developers have to go back to the docs, constantly, to deal with quirks.
• More parity between the site and the API. Allowing developers to replicate the entire site, pretty much (e.g. Japanese users localizing all of Twitter.)

Business - What’s the business case for an API?

• It’s a loss-leader, getting some of your users to come to the site, some of the time.
• Mashery. Billing is an issue…
• QoS: Charge for higher-performance part of your cluster

Future directions/tech:

• OAuth is a promising standard for APIs. Twitter is leaning towards implementing this; less overhead, more secure.
• Jabber/XMPP is perfect for Twitter (less so for Instructables, for most of our content.) Push, generally. See also GNIP, which is also trying to solve this problem.
• Web -> API -> SOA (Service-Oriented Architecture.) A clean separation of concerns

Michal Migurski (Stamen Design)

Loosely Joining Small Pieces - Physical metaphors are useful when thinking of APIs (pieces, things, joints.)

Example: Oakland Crimespotting taking OPD’s crimewatch data and exposing it in more useful, packaged formats. Surfacing the map right up front, making it easy to slice data in time and space and also in unique buckets like particular police beats. Opens up various formats like downloadable spreadsheets.

Digg Labs: experimenting with various cool visualizations

Knowns:

• Should Just Work in a browser
• Key registration is a hassle to be avoided. One approach is to create whole accounts (heavyweight.) Or, it can be completely open. A middle-of-the-road approach is to ask calls to identify themselves by URL. Thus, if there’s any problem, you can just go there and see if it looks like a reasonable use and contact someone if necessary.
• Do all of your dates as Unix timestamps
• Stick to core formats. In order: XML, JSON, serialized PHP, Javascript callbacks (to get around cross-domain restrictions)

XML: Homegrown document type. Extending an existing document type is a hassle.

REST: just web-jargon for Moving Things instead of Doing Stuff. Better yet, URLs should as readable as possible. See Digg or Flickr’s URLs for things.

News To Us, future directions:

• Unit tests are the single best way to coordeinate design and devleopment
• Expect your database to change. Check out Amazon S3
• OAuth: delegated authentication

Related Posts:

• Building the Facebook Platform (November, 2007)
• Analytics 2.0 (April, 2007)
• Web 2.0 Notes: Brian Dillard on Hacking the Browser (April, 2008)
• Web2.0 Notes: Surfacing Personal Information (April, 2008)
• Empirical Design Using Analytics (April, 2007)

This entry was posted on Wednesday, April 23rd, 2008 at 2:45 pm and is filed under coding, instructables. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.