1. Design Your API
Learnings From Twitter + Stamen

2. Basics
We don’t need to define what an API is at this point...

3. 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?

4. (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.

5. Provider
I’m coming from the perspective of developing, maintaining, and providing an API.

6. The Twitter API
‣ Comprises most of Twitter’s web traffic.
‣ ~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.

7. Grow it organically.
Never really promoted the Twitter API. Community has set the direction, helped shape the
API.

8. Document.
Things really took off when we formally documented the API. Take the time to write
thorough documentation.

9. Support.
Start a community. Get involved. Listen. Delegate.

10. Scale.
Think about scale sooner than later: rate limits, extra servers, partitioning.

11. 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

12. 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...

13. New In The Twitter API
‣ Introductory location support.
‣ More consistency between methods.
‣ More parity between the site and the API.

14. Business.
The role of APIs in becoming a profitable web business is complicated. For new companies,
it’s essential. For established companies, it’s optional, and so they often get it wrong.

15. $
Money Making?
‣ API as loss-leader.
‣ Mashery?
‣ QoS.
Additional anecdote: Twitteriffic making money of our API even though we don’t.

16. Future!
What’s next for people providing APIs?

17. OAuth

18. Jabber/XMPP

19. Push?
Something easier than XMPP - HTTP based, like Comet? Gnip.

20. 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.

21. 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.

23. - Oakland Police Department's CrimeWatch website had no usable data layer, Crimespotting is a
technological guerilla action to create one.

24. “Get into those individual crimes”

26. - We're intentionally trying to stretch the definition of quot;APIquot; here: the classic, Flickr-driven concept of
an XML web service is definitely one Web 2.0 compliant way of looking at things, but Excel files 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.

27. 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.

29. 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

31. Static URLs
Things should stay where you left them.

32. 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.

36. Knowns
Should Just Work in a browser.
Key registration is a hassle to be avoided.
Do all of your dates as Unix timestamps.
Stick to these core formats: XML, JSON,
serialized PHP, Javascript callbacks.
- Things we knew going in: most of our decisions were focused on making API use as easy as possible
for data consumers: Just Works in a browser, no API key signup, four different formats (XML, JSON,
javascript with callbacks, serialized PHP), dates are Unix timestamps because every client language
knows how to handle these.

37. JSON
Response
{ “stories”: [ {“title”: ... }, ... ] }
Javascript
response.stories[0].title
- JSON responses are built for ease of iteration and descent, e.g.
quot;response.stories[0].user.namequot; and so on.

38. 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.

39. REST
“REST” is just web-jargon for
Moving Things instead
of Doing Stuff.

42. 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[0].user.namequot; and so on.

43. 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 find 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?

44. 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.

45. Coming Up

46. 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.

47. 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.

48. ¡Thank You!
¿Questions?
- There's a universe of cool stuff that you can't predict. An open interface signals readiness for
whatever may come.

49. 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/