0
What Makes aGreat Open API?   John Musser   CEO, ProgrammableWeb   @johnmusser
Safe Harbor Safe harbor statement under the Private Securities Litigation Reform Act of 1995: This presentation may contai...
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 cal...
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, )                                             …        ...
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
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 APIservice hides many sins
A great API on a bad servicethe API Value Corollary                          is lipstick on a pig
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 face many design questions What protocol(s) will I support?                               What data format(s) to pr...
What is the price of IBM?POST /GetStock HTTP/1.1                            GET http://example.org/stock/IBMHost: www.exam...
SOAP                                                RESTPOST /GetStock HTTP/1.1                            GET http://exam...
API protocols and stylesBased on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012
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 storyis…                      A great API                     understands                     its au...
Your audience may <3 SOAP, really 50+ finance APIs, 5 billion+ calls/month
Best data format? It depends… XML, JSON, RSS, Atom, YAML, iCalendar, CSV,  Serialized PHP, HTML, PNG, GeoRSS, vCard,Text, ...
What is the price of IBM?{                       <?xml version="1.0"?>    "symbol": ”IBM",    <soap:Envelope    "price": 9...
JSON                             XML{                      <?xml version="1.0"?>    "symbol": ”IBM",   <soap:Envelope    "...
Percentage of REST APIs supporting JSON    Based on directory of 6,200 web APIs listed at ProgrammableWeb, June 2012
Want to discuss API design?       Check out API Crafthttp://groups.google.com/group/api-craft
5 Keys to a Great API          Valuable           Planned  (simple) Flexible (easily adopted)          Managed         Sup...
API simplicity continuumSimple                                 Complex    “As simple as possible, but no simpler”
What makes an API flexible?            Provides choices         data format, protocol, version        Gives developer cont...
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 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                                        ...
5 Keys to a Great API       Valuable       Planned       Flexibile       Managed (easily adopted)      Supported
What to manage & measure?  Manage           Measure  Security         Performance  Key management   Developers and apps  M...
API versioning in RESTWhere                What           Who        ExamplePath segment         Date           Twilio    ...
It matters less howyou 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 meausred
Metrics that matter Traffi              Developers            Service                      Total developers      Performan...
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)   signup, guides, reference, SDKs, pricing, clear ToS      ...
developerexperience.org                see alsodeveloper-support-handbook.appspot.com
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                respo...
Community:never underestimate the value
5 Keys to a Great API       Valuable       Planned       Flexible       Managed      Supported
Top 10 API worst practices    10. Poor error handing    9.  REST APIs that ignore HTTP rules    8.  Exposing your raw unde...
A great API  is a journey,not a destination
Thank You       Questions, ideas,comments?john@programmablewe            b.com       @johnmusser
Photo CreditsPig: http://www.flickr.com/photos/babasteve/7341687640/Race car: http://www.flickr.com/photos/lim_lik_wei/327...
What Makes a Great Open API?
Upcoming SlideShare
Loading in...5
×

What Makes a Great Open API?

1,245

Published on

Transcript of "What Makes a Great Open API?"

  1. 1. What Makes aGreat Open API? John Musser CEO, ProgrammableWeb @johnmusser
  2. 2. Safe Harbor Safe harbor statement under the Private Securities Litigation Reform Act of 1995: This presentation may contain forward-looking statements that involve risks, uncertainties, and assumptions. If any such uncertainties materialize or if any of the assumptions proves incorrect, the results of salesforce.com, inc. could differ materially from the results expressed or implied by the forward-looking statements we make. All statements other than statements of historical fact could be deemed forward-looking, including any projections of product or service availability, subscriber growth, earnings, revenues, or other financial items and any statements regarding strategies or plans of management for future operations, statements of belief, any statements concerning new, planned, or upgraded services or technology developments and customer contracts or use of our services. The risks and uncertainties referred to above include – but are not limited to – risks associated with developing and delivering new functionality for our service, new products and services, our new business model, our past operating losses, possible fluctuations in our operating results and rate of growth, interruptions or delays in our Web hosting, breach of our security measures, the outcome of intellectual property and other litigation, risks associated with possible mergers and acquisitions, the immature market in which we operate, our relatively limited operating history, our ability to expand, retain, and motivate our employees and manage our growth, new releases of our service and successful customer deployment, our limited history reselling non-salesforce.com products, and utilization and selling to larger enterprise customers. Further information on potential factors that could affect the financial results of salesforce.com, inc. is included in our annual report on Form 10-Q for the most recent fiscal quarter ended July 31, 2012. This documents and others containing important disclosures are available on the SEC Filings section of the Investor Information section of our Web site. Any unreleased services or features referenced in this or other presentations, press releases or public statements are not currently available and may not be delivered on time or at all. Customers who purchase our services should make the purchase decisions based upon features that are currently available. Salesforce.com, inc. assumes no obligation and does not intend to update these forward- looking statements.
  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 model Simple, 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. 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. A very valuable APIservice hides many sins
  21. 21. A great API on a bad servicethe API Value Corollary 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 face many design questions What 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 is the price of IBM?POST /GetStock HTTP/1.1 GET http://example.org/stock/IBMHost: www.example.orgContent-Type: application/soap+xml<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"><soap:Bodyxmlns:m="http://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 http://example.org/stock/IBMHost: www.example.orgContent-Type: application/soap+xml<?xml version="1.0"?><soap:Envelopexmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"><soap:Bodyxmlns:m="http://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 6,200 web APIs listed at ProgrammableWeb, June 2012
  29. 29. 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 storyis… A great API understands its audience
  33. 33. Your audience may <3 SOAP, really 50+ finance APIs, 5 billion+ calls/month
  34. 34. Best 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 is the price of IBM?{ <?xml version="1.0"?> "symbol": ”IBM", <soap:Envelope "price": 94.72, xmlns:soap="http://www.w3.org/2001/12/soap-envelope"} soap:encodingStyle="http://www.w3.org/2001/12/soap- encoding"> <soap:Body xmlns:m="http://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="http://www.w3.org/2001/12/soap-envelope"} soap:encodingStyle="http://www.w3.org/2001/12/soap- encoding"> <soap:Body xmlns:m="http://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 6,200 web APIs listed at ProgrammableWeb, June 2012
  38. 38. Want to discuss API design? Check out API Crafthttp://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 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 Wordnik’s Swagger & Mashery’s I/O Docs Playground Apigee’s API console Twilio’s debugger
  51. 51. 5 Keys to a Great API Valuable Planned Flexibile Managed (easily adopted) 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 ExamplePath segment Date Twilio /2010-04-01/…Path segment Number Twitter /1/…Path segment ‘v’ + Number LinkedIn /v1/…Query string Number Google ?v=2Custom HTTP header Number Google GData-Version: 2HTTP Accept header Number Github application/vnd.github[.version]
  54. 54. It matters less howyou 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 meausred
  57. 57. Metrics that matter Traffi Developers Service Total developers Performance c Active developers Availability Total calls Top developers Error rates Top methods Trending apps Code defects Call chainsMarketing Quota faults Support BusinessDev registrations Support tickets Direct revenueDev portal funnel Response times Indirect revenue Traffic sources Community metrics Market share Event metrics Costs
  58. 58. 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) 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
  63. 63. developerexperience.org see alsodeveloper-support-handbook.appspot.com
  64. 64. 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:never underestimate the value
  68. 68. 5 Keys to a Great API Valuable Planned Flexible 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. A great API is a journey,not a destination
  71. 71. Thank You Questions, ideas,comments?john@programmablewe b.com @johnmusser
  72. 72. Photo CreditsPig: http://www.flickr.com/photos/babasteve/7341687640/Race car: http://www.flickr.com/photos/lim_lik_wei/3270522646/Stopwatch: http://www.flickr.com/photos/purplemattfish/3020016417/Hackers: http://www.flickr.com/photos/hackny/5684846071/Winding road: http://www.flickr.com/photos/matthewthecoolguy/7518274258/
  1. A particular slide catching your eye?

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

×