0
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	                         ...
API Billionaires Club  13 billion API calls / day (May 2011)  5 billion API calls / day     (April 2010)  5 billion API ca...
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...
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
5 Keys to a Great API       Valuable       Planned       Flexible       Managed      Supported
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 lipstic...
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?          ...
You’ll make many design choicesWhat protocol(s) will I support?                       What data format(s) to provide?     ...
What’s the price of IBM?POST	  /GetStock	  HTTP/1.1	                      GET	  h@p://example.org/stock/IBM	  Host:	  www....
SOAP                                             RESTPOST	  /GetStock	  HTTP/1.1	                      GET	  h@p://example...
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
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, R...
What’s the price of IBM?{	                                       <?xml	  version="1.0"?>	  	  	  	  	  "symbol":	  ”IBM",	...
JSON                                             XML{	                                       <?xml	  version="1.0"?>	  	  ...
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         S...
API simplicity continuumSimple                               Complex  “As simple as possible, but no simpler”
What makes an API flexible?             Provides choices        data format, protocol, version         Gives developer con...
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                                              Goog...
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  M...
API versioning in RESTWhere	                        What	               Who	            Example	  Path	  segment	         ...
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 ma...
Great APIs get measured       Great APIs get measured
Metrics that matter Traffic            Developers          Service                     Total developers    Performance  To...
ET #5      I SECRA   P    Great APIs prioritize     what they want to          measure
“The absence oflimitations 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    ...
What makes an API supported?    Great developer experience (DX)              	          A   nd reference, SDKs, pricing, l...
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     …	            Flexi...
Top 10 API worst practices  10. Poor error handing  9. REST APIs that ignore HTTP rules  8. Exposing your raw underlying d...
#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_l...
Upcoming SlideShare
Loading in...5
×

What Makes a Great Open API?

56,726

Published on

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

Published in: Technology, Education
8 Comments
191 Likes
Statistics
Notes
No Downloads
Views
Total Views
56,726
On Slideshare
0
From Embeds
0
Number of Embeds
90
Actions
Shares
0
Downloads
1,325
Comments
8
Likes
191
Embeds 0
No embeds

No notes for slide

Transcript of "What Makes a Great Open API?"

  1. 1. What Makes aGreat Open API? John  Musser,  ProgrammableWeb   @johnmusser   OSCON  2012    
  2. 2. yea rs  7   Is   ,000  AP tor ies   6  new s  s 3 ,000
  3. 3. Why does having a great API matter?
  4. 4. API growth rateBased on directory of 6,000 web APIs listed at ProgrammableWeb, May 2012
  5. 5. 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
  6. 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. 7. Apps & devices everywhere
  8. 8. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
  9. 9. 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
  10. 10. Each “key” has two sides:business & technology (each supports the other)
  11. 11. Each “key” has two sides:business & technology (today’s talk)
  12. 12. ET #1 I SECRA P These are really, really hard to do right
  13. 13. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
  14. 14. Valuable Service
  15. 15. Valuable Data
  16. 16. Valuable Audience
  17. 17. Valuable Function
  18. 18. Valuable Marketplace
  19. 19. Valuable Access
  20. 20. ET #2 I SECRA PA very valuable service hides many API sins
  21. 21. the API Value Corollary The API value corollary A great API on a bad service is lipstick on a pig
  22. 22. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
  23. 23. 5 Keys to a Great API Valuable Planned (designed) Flexible Managed Supported
  24. 24. Your first two design questions What is the goal of this API? (purpose) Who will be using this API? (audience)
  25. 25. 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…
  26. 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. 27. 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>  
  28. 28. API protocols and stylesBased on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
  29. 29. ET #3 I SECRA P A great API doesn’t just ask“am I RESTful enough? ”
  30. 30. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
  31. 31. Daniel Jacobson, Netflix Engineering Blog, July 9, 2012
  32. 32. another moral of that story is… A great API understands its audience
  33. 33. Your audience may <3 SOAP, really 50+ finance APIs, 5 billion+ calls/month
  34. 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. 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. 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. 37. Percentage of REST APIs supporting JSON Based on directory of 5,800 web APIs listed at ProgrammableWeb, May 2012
  38. 38. Want to discuss API design? Check out API Craft http://groups.google.com/group/api-craft
  39. 39. 5 Keys to a Great API Valuable Planned (simple) Flexible (easily adopted) Managed Supported
  40. 40. API simplicity continuumSimple Complex “As simple as possible, but no simpler”
  41. 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. 42. What’s your TTFHW? Time To First “Hello World” aka: how long from zero to 60?
  43. 43. 6 ways to accelerate TTFHW
  44. 44. #1) Make it clear what you do
  45. 45. #2) Offer “Free” or “Trial” API access
  46. 46. (or, even both free & trial)
  47. 47. #3) Fast, automated signup (so fast, you can even skip this step till you’re convinced…)
  48. 48. #4) Clear, accurate documentation
  49. 49. #5) Copious code samples
  50. 50. Stripe’s dashboard #6) Provide tools Google’s OAuth Playground Wordnik’s Swagger & Mashery’s I/O Docs Apigee’s API consoleTwilio’s debugger
  51. 51. 5 Keys to a Great API Valuable Planned Flexible Managed (and measured) Supported
  52. 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. 53. 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]  
  54. 54. ET #4 I SECRA PIt matters less how you version than you do version
  55. 55. 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)
  56. 56. Great APIs get measured Great APIs get measured
  57. 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 RetentionMarketing Support BusinessDev registrations Direct revenue Support tickets Indirect revenueDev portal funnel Response times Market share Traffic sources Community metrics Costs Event metrics
  58. 58. ET #5 I SECRA P Great APIs prioritize what they want to measure
  59. 59. “The absence oflimitations is the enemy of art” Orson Welles
  60. 60. 5 Keys to a Great API Valuable Planned Flexible Managed Supported
  61. 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. 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. 63. developerexperience.org see alsodeveloper-support-handbook.appspot.com
  64. 64. ET #6 I SECRA P Great DX separates the best APIs from the rest
  65. 65. Covering your DX checklist
  66. 66. Does API design impact support? Let me count the ways… For example, look at Twilio’s error response
  67. 67. Community: a core tenet of greatopen APIs and open source
  68. 68. 5 Keys to a Great API Valuable e   e  m or A nd on  Planned ing …   Flexible th Managed Supported
  69. 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. 70. #7 P I SECR ET A great APIA is a journey, not a destination
  71. 71. Thank You QuesRons,  ideas,  comments?john@programmableweb.com   @johnmusser    
  72. 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/      
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×