• Like
What Makes a Great Open API?
Upcoming SlideShare
Loading in...5
×

What Makes a Great Open API?

  • 52,431 views
Uploaded 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 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".

More in: Technology , Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
  • video presentation from qcon 2013 that follows this deck
    http://www.infoq.com/presentations/api-design-advice
    Are you sure you want to
    Your message goes here
  • Awesome slide set - we wrote a series of blog posts trying to drill down on each of these topics: http://www.3scale.net/2012/11/building-great-apis-the-api-gold-standard-part-i/ (about to wrap up with the final post!).
    Are you sure you want to
    Your message goes here
  • Awesome
    Are you sure you want to
    Your message goes here
  • @johnmusser Thank you for great tips! It's really helpfull as we still working on our image recognition api recognize.im
    It's really helpfull!
    Are you sure you want to
    Your message goes here
  • @jmusser makes sense, thanks a ton for the great work. Awesome deck.
    Are you sure you want to
    Your message goes here
No Downloads

Views

Total Views
52,431
On Slideshare
0
From Embeds
0
Number of Embeds
81

Actions

Shares
Downloads
1,095
Comments
7
Likes
171

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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/