What is it that turns an ordinary API into a great API? This talk from OSCON 2012 outlines the 5 "keys" to having a great API. Lots of examples from successful real-world APIs are used to highlight what matters. Also, this talk reveals 7 lesser known but very important "API secrets".

1. What Makes a
Great Open API?
John
Musser,
ProgrammableWeb
@johnmusser
OSCON
2012

2. yea rs
7
Is
,000
AP tor ies
6
new s
s
3 ,000

3. Why does having
a great API
matter?

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

5. 3
Months
4
Months
6
Months
9
Months
18
Months
8
Years
API growth rate
Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

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

7. Apps & devices everywhere

8. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

9. 5 Keys to a Great API
A valuable service (data, function, audience, )
…
A plan and a business model
Simple, flexible, easily adopted
Managed and measured
Great developer support

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

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

12. ET #1
I SECR
A P
These are really,
really hard to do
right

13. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

14. Valuable Service

15. Valuable Data

16. Valuable Audience

17. Valuable Function

18. Valuable Marketplace

19. Valuable Access

20. ET #2
I SECR
A P
A very valuable service
hides many API sins

21. the API Value Corollary
The API value corollary
A great API on a bad service
is lipstick on a pig

22. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

23. 5 Keys to a Great API
Valuable
Planned (designed)
Flexible
Managed
Supported

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

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

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

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

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

29. ET #3
I SECR
A P
A great API doesn’t
just ask
“am I RESTful enough? ”

30. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

31. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012

32. another moral of that story is…
A great API
understands its
audience

33. Your audience may <3 SOAP, really
50+ finance APIs, 5 billion+ calls/month

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

35. What’s the price of IBM?
{
<?xml
version="1.0"?>
"symbol":
”IBM",
<soap:Envelope
"price":
94.72,
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:GetStockPriceResponse>
<m:Price>34.5</m:Price>
</m:GetStockPriceResponse>
</soap:Body>
</soap:Envelope>

36. JSON XML
{
<?xml
version="1.0"?>
"symbol":
”IBM",
<soap:Envelope
"price":
94.72,
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:GetStockPriceResponse>
<m:Price>34.5</m:Price>
</m:GetStockPriceResponse>
</soap:Body>
</soap:Envelope>

37. Percentage of REST APIs supporting JSON
Based on directory of 5,800 web APIs listed at ProgrammableWeb, May 2012

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

39. 5 Keys to a Great API
Valuable
Planned
(simple) Flexible (easily adopted)
Managed
Supported

40. API simplicity continuum
Simple Complex
“As simple as possible, but no simpler”

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

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

43. 6 ways to accelerate TTFHW

44. #1) Make it clear what you do

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

46. (or, even both free & trial)

47. #3) Fast, automated signup
(so fast, you can even skip this
step till you’re convinced…)

48. #4) Clear, accurate documentation

49. #5) Copious code samples

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

51. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed (and measured)
Supported

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

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

54. ET #4
I SECR
A P
It matters less how you
version than you do
version

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

56. Great APIs get measured
Great APIs get measured

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

58. ET #5
I SECR
A P
Great APIs prioritize
what they want to
measure

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

60. 5 Keys to a Great API
Valuable
Planned
Flexible
Managed
Supported

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

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

63. developerexperience.org
see also
developer-support-handbook.appspot.com

64. ET #6
I SECR
A P
Great DX separates
the best APIs from
the rest

65. Covering your DX checklist

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

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

68. 5 Keys to a Great API
Valuable e
e
m or
A nd on
Planned
ing …
Flexible
th
Managed
Supported

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

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

71. Thank You
QuesRons,
ideas,
comments?
john@programmableweb.com
@johnmusser

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