What Makes a Great Open API?

What Makes a
Great Open API?
John
Musser,
ProgrammableWeb

@johnmusser

OSCON
2012

yea rs

7
Is

,000
AP tor ies

6

new s
s
3 ,000

Why does having
a great API
matter?

API growth rate
Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

3
Months

4
Months

6
Months

9
Months

18
Months

8
Years

API growth rate

API Billionaires Club
13 billion API calls / day (May 2011)
5 billion API calls / day (April 2010)

5 billion API calls / day (October 2009)

1.4 billion API calls / day (May 2012)

1.1 billion API calls / day (April 2011)

1 billion API calls / day (May 2012)
1 billion API calls / day (Q1 2012)

1 billion API calls / day (January 2012)

5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

A valuable service (data, function, audience, )
…

A plan and a business model
Simple, flexible, easily adopted
Managed and measured
Great developer support

Each “key” has
two sides:
business & technology
(each supports the other)

Each “key” has
two sides:
business & technology
(today’s talk)

ET #1
I SECR
A P

These are really,
really hard to do
right

ET #2
I SECR
A P

A very valuable service
hides many API sins

the API Value Corollary
The API value corollary

A great API on a bad service
is lipstick on a pig

Valuable
Planned (designed)
Flexible
Managed
Supported

Your first two design questions
What is the goal of this API?
(purpose)
Who will be using this API?
(audience)

You’ll make many design choices
What protocol(s) will I support?
What data format(s) to provide?
How will I manage security?
Should I use an open source framework?
Which design patterns to use? Hmm, are there any?
Oh, right, I need to do versioning too…

What’s the price of IBM?
POST
/GetStock
HTTP/1.1
GET
h@p://example.org/stock/IBM

Host:
www.example.org

Content-‐Type:
applicaRon/soap+xml

<?xml
version="1.0"?>

<soap:Envelope

xmlns:soap="h@p://www.w3.org/2001/12/soap-‐
envelope"

soap:encodingStyle="h@p://www.w3.org/
2001/12/soap-‐encoding">

<soap:Body
xmlns:m="h@p://www.example.org/
stock">

<m:GetStockPrice>

<m:StockName>IBM</m:StockName>

</m:GetStockPrice>

</soap:Body>

</soap:Envelope>

SOAP REST
POST
/GetStock
HTTP/1.1
GET
h@p://example.org/stock/IBM

Host:
www.example.org

Content-‐Type:
applicaRon/soap+xml

<?xml
version="1.0"?>

<soap:Envelope

envelope"


<soap:Body
stock">

<m:GetStockPrice>

<m:StockName>IBM</m:StockName>

</m:GetStockPrice>

</soap:Body>

</soap:Envelope>

API protocols and styles
Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012

ET #3
I SECR
A P

A great API doesn’t
just ask
“am I RESTful enough? ”

Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

another moral of that story is…

A great API
understands its
audience

Your audience may <3 SOAP, really

50+ finance APIs, 5 billion+ calls/month

Data format? It depends…
XML, JSON, RSS, Atom, YAML,
iCalendar, CSV, Serialized PHP, HTML,
PNG, GeoRSS, vCard, Text, RDF, OPML,
MediaRSS, VML, TV-Anytime,
hCalendar, FOAF, XSPF, SQL, GML, CDF

Data formats supported by APIs on ProgrammableWeb, May 2012

What’s the price of IBM?
{
<?xml
version="1.0"?>

"symbol":
”IBM",
<soap:Envelope

"price":
94.72,
envelope"

}


<soap:Body
stock">

<m:GetStockPriceResponse>

<m:Price>34.5</m:Price>

</m:GetStockPriceResponse>

</soap:Body>

</soap:Envelope>

JSON XML
{
<?xml
version="1.0"?>

"symbol":
”IBM",
<soap:Envelope

"price":
94.72,
envelope"

}


<soap:Body
stock">

<m:GetStockPriceResponse>

<m:Price>34.5</m:Price>

</m:GetStockPriceResponse>

</soap:Body>

</soap:Envelope>

Percentage of REST APIs supporting JSON

Want to discuss API design?
Check out API Craft
http://groups.google.com/group/api-craft

Valuable
Planned
(simple) Flexible (easily adopted)

Managed
Supported

API simplicity continuum

Simple Complex

“As simple as possible, but no simpler”

What makes an API flexible?
Provides choices
data format, protocol, version

Gives developer control
partial queries & updates, batch operations

Offers advanced options
webhooks, streaming, caching

What’s your TTFHW?
Time To First “Hello World”
aka: how long from zero to 60?

#2) Offer “Free” or “Trial” API access

#3) Fast, automated signup

(so fast, you can even skip this
step till you’re convinced…)

#4) Clear, accurate documentation

Stripe’s dashboard
#6) Provide tools
Google’s
OAuth
Playground
Wordnik’s Swagger & Mashery’s I/O Docs

Apigee’s API console

Twilio’s debugger

Valuable
Planned
Flexible
Managed (and measured)
Supported

What to manage & measure?
Manage Measure
Security Performance
Key management Developers and apps
Monitoring Quality
Reporting Marketing
Scaling Revenue
Rate limiting Volume
Versioning Trends

API versioning in REST
Where
What
Who
Example

Path
segment
Date
Twilio
/2010-‐04-‐01/…

Path
segment
Number
Twi@er
/1/…

Path
segment
‘v’
+
Number
LinkedIn
/v1/…

Query
string
Number
Google
?v=2

Custom
HTTP
header
Number
Google
GData-‐Version:
2

HTTP
Accept
header
Number
Github
applicaRon/vnd.github[.version]

ET #4
I SECR
A P

It matters less how you
version than you do
version

API security baseline
Today:
SSL as option
OAuth 2.0 (one of the few API standards with traction)
Future:
SSL required (many major APIs moving to SSL only)
OpenID Connect (it’s very early today)

Great APIs get measured
Great APIs get measured

Metrics that matter
Traffic Developers Service
Total developers Performance
Total calls
Active developers Availability
Top methods
Top developers Error rates
Call chains
Trending apps Code defects
Quota faults
Retention

Marketing Support Business
Dev registrations Direct revenue
Support tickets Indirect revenue
Dev portal funnel
Response times Market share
Traffic sources
Community metrics Costs
Event metrics

ET #5
I SECR
A P

Great APIs prioritize
what they want to
measure

“The absence of
limitations is the
enemy of art”
Orson Welles

What makes an API supported?
Great developer experience (DX)
signup, guides, reference, SDKs, pricing, clear ToS

Communication & community
forum, blog, social media, email, app gallery

Great support / evangelism teams
active, engaged, listening, responding, at events

What makes an API supported?
Great developer experience (DX)

A nd reference, SDKs, pricing, legal
g

Signup, guides,
ythin
er & communityr

ev
Communication d
un de
c ereemail, events, clear ToS
forum, blog,ov media,
social

/W

teams
Great supportHevangelism
TF
T listening, responding
active, engaged,

developerexperience.org

see also
developer-support-handbook.appspot.com

ET #6
I SECR
A P

Great DX separates
the best APIs from
the rest

Does API design impact support?
Let me count the ways…
For example, look at Twilio’s error response

Community: a core tenet of great
open APIs and open source

Valuable e

e
m or
A nd on

Planned
ing …

Flexible
th
Managed
Supported

Top 10 API worst practices
10. Poor error handing
9. REST APIs that ignore HTTP rules
8. Exposing your raw underlying data model
7. Security complexity
6. Unexpected & undocumented releases
5. Poor developer experience
4. Expect an MVC framework ‘gives’ you a great API
3. Assume if you build it they will come
2. Inadequate support
1. Poor documentation

#7
P I SECR ET A great API
A
is a journey,
not a destination

Thank You

QuesRons,
ideas,
comments?
john@programmableweb.com

@johnmusser

Photo
credits

Pig:
h@p://www.flickr.com/photos/babasteve/7341687640/

Race
car:
h@p://www.flickr.com/photos/lim_lik_wei/3270522646/

Stopwatch:
h@p://www.flickr.com/photos/purplemapish/3020016417/

Hackers:
h@p://www.flickr.com/photos/hackny/5684846071/

Winding
road:
h@p://www.flickr.com/photos/ma@hewthecoolguy/7518274258/

What Makes a Great Open API?

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to What Makes a Great Open API?

Similar to What Makes a Great Open API? (20)

Recently uploaded

Recently uploaded (20)

What Makes a Great Open API?