What Makes a Great Open API?

What Makes aGreat 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 rateBased 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 rateBased on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012

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)

Apps & devices everywhere

5 Keys to a Great API Valuable Planned Flexible Managed Supported

5 Keys to a Great APIA valuable service (data, function, audience, ) … A plan and a business modelSimple, 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 SECRA P These are really, really hard to do right

Valuable Service

Valuable Data

Valuable Audience

Valuable Function

Valuable Marketplace

Valuable Access

ET #2 I SECRA PA 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

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 choicesWhat 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 RESTPOST /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>

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

ET #3 I SECRA 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, 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{ <?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>

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

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

5 Keys to a Great API 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 RESTWhere 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 SECRA PIt matters less how you version than you do version

API security baselineToday:SSL as optionOAuth 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 RetentionMarketing Support BusinessDev registrations Direct revenue Support tickets Indirect revenueDev portal funnel Response times Market share Traffic sources Community metrics Costs Event metrics

ET #5 I SECRA P Great APIs prioritize what they want to measure

“The absence oflimitations 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 alsodeveloper-support-handbook.appspot.com

ET #6 I SECRA P Great DX separates the best APIs from the rest

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 greatopen APIs and open source

5 Keys to a Great API 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 APIA 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/