designing your api

49
Design Your API Learnings From Twitter + Stamen

Upload: alex-payne

Post on 15-Jan-2015

27.303 views

Category:

Technology


1 download

DESCRIPTION

Learnings from Twitter and Stamen.

TRANSCRIPT

Page 1: Designing Your API

Design Your APILearnings From Twitter + Stamen

Page 2: Designing Your API

Basics

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

Page 3: Designing Your API

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?

Page 4: Designing Your API

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

Page 5: Designing Your API

Provider

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

Page 6: Designing Your API

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.

Page 7: Designing Your API

Grow it organically.

Never really promoted the Twitter API. Community has set the direction, helped shape the API.

Page 8: Designing Your API

Document.

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

Page 9: Designing Your API

Support.

Start a community. Get involved. Listen. Delegate.

Page 10: Designing Your API

Scale.

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

Page 11: Designing Your API

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

Page 12: Designing Your API

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

Page 13: Designing Your API

New In The Twitter API

‣ Introductory location support.

‣ More consistency between methods.

‣ More parity between the site and the API.

Page 14: Designing Your API

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.

Page 15: Designing Your API

Money Making?$‣ API as loss-leader.

‣ Mashery?

‣ QoS.

Additional anecdote: Twitteriffic making money of our API even though we don’t.

Page 16: Designing Your API

Future!

What’s next for people providing APIs?

Page 17: Designing Your API

OAuth

Page 18: Designing Your API

Jabber/XMPP

Page 19: Designing Your API

Push?

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

Page 20: Designing Your API

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.

Page 21: Designing Your API

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.

Page 22: Designing Your API
Page 23: Designing Your API

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

Page 24: Designing Your API

“Get into those individual crimes”

Page 25: Designing Your API
Page 26: Designing Your API

- We're intentionally trying to stretch the definition of "API" 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 "handles" that visitors can connect with.

Page 27: Designing Your API

FormatsXML, spreadsheets compatible with Excel, static visual maps suitable for copy-paste, plain HTML, e-mail, Atom + GeoRSS, etc.

We borrow what's useful.

Page 28: Designing Your API
Page 29: Designing Your API

Aggravated Assault

6:14am

Wednesday, Mar 5, 2008

ATTEMPTED MURDER:FIRST

DEGREE (08-016924)

Murder

6:14am

Wednesday, Mar 5, 2008

MURDER (08-016924)

Murder

5:48am

Wednesday, Mar 5, 2008

MURDER (08-016924-002)

Aggravated Assault

5:48am

Wednesday, Mar 5, 2008

ATTEMPTED MURDER:FIRST

DEGREE (08-016924-003)

Burglary

12:20pm

Wednesday, Mar 5, 2008

(7 hours later)

BURGLARY-NO FORCE

(08-017167)

Narcotics

10:40am

Wednesday, Mar 5, 2008

(5 hours later)

POSSESS/PURCHASE COCAINE

BASE FOR SALE (08-017006)

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.

Comments

1. http://www.ktvu.com/news/15500985/detail.html

"Just hours after an Oakland City Council vote to add more officers to its police force, a

neighborhood bus stop was riddled with gunfire early Wednesday leaving one person

dead and another wounded.

The death was the city's 28th homicide of the year, far outpacing last where there were

15 homicides by this date.

The latest shooting took place at the corner of San Pablo and Brockhurst with officers

responding to a "shots fired" call at 5:50 a.m."

Posted by Michal Migurski on Tuesday, Mar 11, 2008 2:44pm

Leave a Comment

Leave a comment about report 08-016924-003, especially if you are familiar with the

incident, believe we have incorrect information about the crime report, or know of a

mention in the local news media such as the Oakland Tribune or San Francisco

Chronicle. We also welcome the posting of details obtained directly from Oakland Police

Department crime report requests—see “8. How do I get a copy of a Crime Report?” at

OPD Frequently Asked Questions.

Comments will be displayed on this page, including the name you provide.

What is the Link for?

We!re most interested in two kinds of links: those pointing to relevant news articles about

this report, and those pointing to other possibly-related reports on this website.

Your Name

Link (if any)

No HTML, please. URL!s will be made into links.

comment

Similar Reports

All Reports of Murder on Wednesday, Mar 5, 2008

All crimes on Wednesday, Mar 5, 2008

All Reports of Murder

Nearby Reports

Reports near the one above, from around the same time.

Home Map Crime Reports Police Beats Alerts About Feedback

Contact us at [email protected].

This project is not affiliated with the City of Oakland or the Oakland Police Department.

We use data obtained from CrimeWatch, Oakland's community mapping website.

Please read their disclaimer to understand limitations of the data.

All map content © Microsoft Corporation / Microsoft® Virtual Earth™

Report data last published by Oakland Police: 2 days ago

Home Map Crime Reports Police Beats Alerts About Feedback

Page 30: Designing Your API
Page 31: Designing Your API

Static URLsThings should stay where you left them.

Page 32: Designing Your API

Digg Labs, API2006 – 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.

Page 33: Designing Your API
Page 34: Designing Your API
Page 35: Designing Your API
Page 36: Designing Your API

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

Page 37: Designing Your API

JSON

Response{ “stories”: [ {“title”: ... }, ... ] }

Javascriptresponse.stories[0].title

- JSON responses are built for ease of iteration and descent, e.g. "response.stories[0].user.name" and so on.

Page 38: Designing Your API

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

Page 39: Designing Your API

REST“REST” is just web-jargon for

Moving Things insteadof Doing Stuff.

Page 40: Designing Your API
Page 41: Designing Your API
Page 42: Designing Your API

URLsRequestshttp://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. "response.stories[0].user.name" and so on.

Page 43: Designing Your API

News To UsUnit 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?

Page 44: Designing Your API

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

Page 45: Designing Your API

Coming Up

Page 46: Designing Your API

Amazon S3A 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.

Page 47: Designing Your API

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

Page 48: Designing Your API

¡Thank You!¿Questions?

- There's a universe of cool stuff that you can't predict. An open interface signals readiness for whatever may come.

Page 49: Designing Your API

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/