What Makes a Great Open API?

69,011 views
66,457 views

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
9 Comments
204 Likes
Statistics
Notes
No Downloads
Views
Total views
69,011
On SlideShare
0
From Embeds
0
Number of Embeds
93
Actions
Shares
0
Downloads
1,456
Comments
9
Likes
204
Embeds 0
No embeds

No notes for slide

What Makes a Great Open API?

  1. What Makes aGreat 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 rateBased 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 rateBased 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 APIA valuable service (data, function, audience, ) … A plan and a business modelSimple, 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 SECRA 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 SECRA PA 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 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. 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 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. API protocols and stylesBased on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
  29. ET #3 I SECRA 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 continuumSimple 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 consoleTwilio’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 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. ET #4 I SECRA PIt matters less how you version than you do version
  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. 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 RetentionMarketing Support BusinessDev registrations Direct revenue Support tickets Indirect revenueDev portal funnel Response times Market share Traffic sources Community metrics Costs Event metrics
  58. ET #5 I SECRA P Great APIs prioritize what they want to measure
  59. “The absence oflimitations 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 alsodeveloper-support-handbook.appspot.com
  64. ET #6 I SECRA 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 greatopen 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 APIA 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/      

×