What Makes a Great Open API?
John Musser, ProgrammableWeb @johnmusser OSCON 2012
7 years
6,000 APIs
3,000 news sto
ries
Why does having a great API
matter?
API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012
API growth rate Based on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012
8 Years
18 Months
9 Months
6 Months
4 Months
3 Months
API Billionaires Club 5 billion API calls / day (April 2010)
1 billion API calls / day (Q1 2012)
5 billion API calls / day (October 2009)
13 billion API calls / day (May 2011)
1.4 billion API calls / day (May 2012)
1 billion API calls / day (January 2012)
1.1 billion API calls / day (April 2011)
1 billion API calls / day (May 2012)
Apps & devices everywhere
5 Keys to a Great API Valuable Planned Flexible
Managed Supported
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
Each “key” has two sides:
business technology & (each supports the other)
Each “key” has two sides:
business technology & (today’s talk)
These are really, really hard to do
right
API SECRET #1
5 Keys to a Great API Valuable Planned Flexible
Managed Supported
Valuable Service
Valuable Data
Valuable Audience
Valuable Function
Valuable Marketplace
Valuable Access
A very valuable service hides many API sins
API SECRET #2
The API value corollary
A great API on a bad service is lipstick on a pig
the API Value Corollary
5 Keys to a Great API Valuable Planned Flexible
Managed Supported
5 Keys to a Great API 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?
Which design patterns to use? Hmm, are there any?
Oh, right, I need to do versioning too…
Should I use an open source framework?
GET h@p://example.org/stock/IBM POST /GetStock HTTP/1.1 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>
What’s the price of IBM?
GET h@p://example.org/stock/IBM POST /GetStock HTTP/1.1 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
API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
A great API doesn’t just ask
“am I RESTful enough? ”
API SECRET #3
Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
A great API understands its
audience
another moral of that story is…
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
{ "symbol": ”IBM", "price": 94.72, }
<?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:GetStockPriceResponse> <m:Price>34.5</m:Price> </m:GetStockPriceResponse> </soap:Body> </soap:Envelope>
What’s the price of IBM?
{ "symbol": ”IBM", "price": 94.72, }
<?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:GetStockPriceResponse> <m:Price>34.5</m:Price> </m:GetStockPriceResponse> </soap:Body> </soap:Envelope>
JSON XML
Percentage of REST APIs supporting JSON Based on directory of 5,800 web APIs listed at ProgrammableWeb, May 2012
Want to discuss API design?
Check out API Craft http://groups.google.com/group/api-craft
5 Keys to a Great API 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?
6 ways to accelerate TTFHW
#1) Make it clear what you do
#2) Offer “Free” or “Trial” API access
(or, even both free & trial)
#3) Fast, automated signup
(so fast, you can even skip this step till you’re convinced…)
#4) Clear, accurate documentation
#5) Copious code samples
#6) Provide tools
Twilio’s debugger
Stripe’s dashboard
Wordnik’s Swagger & Mashery’s I/O Docs
Google’s OAuth Playground
Apigee’s API console
5 Keys to a Great API Valuable Planned Flexible
Managed (and measured) Supported
What to manage & measure? Manage
Security Key management Monitoring Reporting Scaling Rate limiting Versioning
Measure
Performance Developers and apps Quality Marketing Revenue Volume 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]
It matters less how you version than you do
version
API SECRET #4
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
Total calls Top methods
Call chains Quota faults
Developers Total developers
Active developers Top developers Trending apps
Retention
Service Performance Availability Error rates
Code defects
Marketing Dev registrations Dev portal funnel
Traffic sources Event metrics
Support Support tickets Response times
Community metrics
Business Direct revenue
Indirect revenue Market share
Costs
Great APIs prioritize what they want to
measure
API SECRET #5
“The absence of limitations is the
enemy of art” Orson Welles
5 Keys to a Great API Valuable Planned Flexible
Managed Supported
What makes an API supported? Great developer experience (DX)
signup, guides, reference, SDKs, pricing, clear ToS
Great support / evangelism teams active, engaged, listening, responding, at events
Communication & community forum, blog, social media, email, app gallery
What makes an API supported? Great developer experience (DX)
Signup, guides, reference, SDKs, pricing, legal
Great support / evangelism teams active, engaged, listening, responding
Communication & community forum, blog, social media, email, events, clear ToS
And everyt
hing
covered unde
r
TTFHW
developerexperience.org
see also developer-support-handbook.appspot.com
Great DX separates the best APIs from
the rest
API SECRET #6
Covering your DX checklist
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
5 Keys to a Great API Valuable Planned Flexible
Managed Supported
And one more
thing…
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
A great API is a journey,
not a destination
API SECRET #7
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/