Published on May 13, 2008
Design Your API Learnings From Twitter + Stamen
Basics We don’t need to deﬁne what an API is at this point...
http://twitter.com/users/show/al3x.json ...but it’s worth explaining where APIs have ended up. This is an example from the API I maintain at Twitter. Can anyone guess what it does?
(It’s basically all about REST) Most providers have decided on REST. Google abandoned SOAP. XML-RPC is gradually being abandoned. This makes a conversation about APIs much simpler.
Provider I’m coming from the perspective of developing, maintaining, and providing an API.
The Twitter API ‣ Comprises most of Twitter’s web trafﬁc. ‣ ~1600 developers in our Google Group. ‣ ~400 applications we credit, tons more out there. ‣ Apps on pretty much every platform. ‣ XML, JSON, RSS, and Atom.
Grow it organically. Never really promoted the Twitter API. Community has set the direction, helped shape the API.
Document. Things really took off when we formally documented the API. Take the time to write thorough documentation.
Support. Start a community. Get involved. Listen. Delegate.
Scale. Think about scale sooner than later: rate limits, extra servers, partitioning.
Secure. * attributes will leak * the integration points between you API and the rest of your site will be tested * little things like crossdomain.xml can have a big impact
What We Did Wrong ‣ Didn’t start with api.twitter.com ‣ Didn’t version the API from the get-go. ‣ Didn’t make life easier for Flash developers. ‣ Didn’t automate to make life easier for us. ‣ Much, much more...
New In The Twitter API ‣ Introductory location support. ‣ More consistency between methods. ‣ More parity between the site and the API.
Business. The role of APIs in becoming a proﬁtable web business is complicated. For new companies, it’s essential. For established companies, it’s optional, and so they often get it wrong.
$ Money Making? ‣ API as loss-leader. ‣ Mashery? ‣ QoS. Additional anecdote: Twitteriffic making money of our API even though we don’t.
Future! What’s next for people providing APIs?
Push? Something easier than XMPP - HTTP based, like Comet? Gnip.
Web→API→SOA A solid development model, and the one Twitter is gradually moving towards. Eat your own dogfood while taking advantage of the separation of concerns that an API inherently gives you. Flickr interestingness example, Google App Engine and AWS development model.
Loosely Joining Small Pieces Pieces, things, joints: physical metaphors that make everything easy. We are envisioning a very near future where web services atomize into tiny bricks of context and functionality, e.g. Dopplr, Fire Eagle, Del.icio.us, Ffffound!, etc. Good API's done right will make this not feel like the decline and fall of the Roman Empire. - There's a universe of cool stuff that you can't predict. An open interface signals readiness for whatever may come.
- Oakland Police Department's CrimeWatch website had no usable data layer, Crimespotting is a technological guerilla action to create one.
“Get into those individual crimes”
- We're intentionally trying to stretch the deﬁnition of quot;APIquot; here: the classic, Flickr-driven concept of an XML web service is deﬁnitely one Web 2.0 compliant way of looking at things, but Excel ﬁles and permanent URLs right there on the website is a broader concept that invites members of the non-geek public to join in. These have all been API-like quot;handlesquot; that visitors can connect with.
Formats XML, spreadsheets compatible with Excel, static visual maps suitable for copy-paste, plain HTML, e-mail, Atom + GeoRSS, etc. We borrow what's useful.
Report data last published by Oakland Police: 2 days ago Home Map Crime Reports Police Beats Alerts About Feedback Murder Wednesday, Mar 5, 2008 5:48am MURDER Case Number 08-016924-003, Police Beat 06X. 3200 block of San Pablo Ave, Emeryville, CA 94608, USA Scroll down to see related and nearby reports, or to leave a comment. View an interactive map of this report. Related Reports These reports are directly related to the one above, and may be part of the same incident. Aggravated Assault Murder Murder Aggravated Assault 6:14am 6:14am 5:48am 5:48am Wednesday, Mar 5, 2008 Wednesday, Mar 5, 2008 Wednesday, Mar 5, 2008 Wednesday, Mar 5, 2008
Static URLs Things should stay where you left them.
Digg Labs, API 2006 – now - Stamen co-designed Digg's web services API in support of our Labs work from 2006. We started with an XML service to support our interactive visualizations, and ended up with a documented, publicly- supported interface.
XML Homegrown document type <?xml version=”1.0” encoding=”utf-8”?> <stories ...> <story id=”...”> <title>...</title> <user name=”...”/> </story> ... </stories> - XML is a custom syntax, trying to shoehorn the semantics onto Atom and RSS via XML namespaces leads only to suffering.
REST “REST” is just web-jargon for Moving Things instead of Doing Stuff.
URLs Requests http://services.digg.com /users /users/migurski/friends /stories /stories/upcoming /stories/topic/apple /stories/topic/apple/popular - JSON responses are built for ease of iteration and descent, e.g. quot;response.stories.user.namequot; and so on.
News To Us Unit tests are the single best way to coordinate design and development. Expect your database to change. - Unit tests were an artifact that we could pass back & forth; Digg would run them and ﬁnd bugs, we'd talk about which tests were valid and which were missing, they acted as a transferrable set of expectations. Python is wonderful for this. - New kinds of queries and new data columns had to be introduced to support certain features that we thought were worthwhile. For example, it's possible to query Digg stories based on domain name e.g. nytimes.com - why doesn't Del.icio.us do this?
Whoops If you defer a feature at launch, it’ll take forever to prioritize again. - What we got wrong: don't leave things off at the start, it gives you a license to leave them off forever. Digg still lacks a writeable API, it's not anybody's fault it's just an easy thing to defer. The world is missing out on a vast array of potential services that Digg users could be building with such a thing.
Amazon S3 A sign of things to come: authentication, utility interface, do one thing and do it best. - More than just data, e.g. Amazon's S3, SQS, etc. - Amazon is building up a stack of services that form the building blocks of distributed computing application and the billing infrastructure that supports them. Amazon's doing some interesting stuff with request authentication and pre-signing.
OAuth Delegated authentication is the missing piece - Small pieces loosely joined by OAuth. There's an OAuth session competing with this one right now, but we think that a vetted standard for 3rd party authentication will help web services make good on their promise by distinguishing between the consumer and the authenticated user, i.e. doing stuff on someone's behalf without invoking the password anti-pattern.
¡Thank You! ¿Questions? - There's a universe of cool stuff that you can't predict. An open interface signals readiness for whatever may come.
Photo Credits http://www.flickr.com/photos/jurvetson/215722930/ http://www.flickr.com/photos/mwichary/2322639175/ http://www.flickr.com/photos/iamagenious/372349393/ http://www.flickr.com/photos/whiskeytango/1431343034/ http://www.flickr.com/photos/carbonnyc/2294144289/
... presented Design Your API: Learnings from Twitter and Stamen. ... Aside from the tickle I get at seeing "Twitter and Stamen ... © Stamen Design ...
Presentation: Design Your API_ Learnings from Twitter and Stamen Presentation [PDF] Web 2.0 ... design firm Stamen.
Design; Devices & Hardware; ... I’ve got a key to your API, ... Design Your Api Learnings From Twitter And Stamen Presentation
Presentation Files. ... Design Your API: Learnings from Twitter and Stamen. ... Design Your API_ Learnings from Twitter and Stamen Presentation [PDF] ...
Yahoo MP3 API Porting a browser Google, SWF SDK ... Disruptive design Different kinds of tech Battery, ... Ignore "Your Account"
COURSES. Sort by Tier ... Affordable 3D Printing and Design – Ready for Your Studio (ITPG-GT.2505) ... Pitching Your Projects as Branded Content ...
True Ventures Facebook fan page social media analytics, analysis, measurement, performance and reports. ... Twitter; Google+; LinkedIn; English; Türkçe ...