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".
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)
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
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>
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?
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)
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
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,
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