Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
What Makes a
Great Open API?
  John	
  Musser,	
  ProgrammableWeb	
  
             @johnmusser	
  
              OSCON	
  ...
yea  rs	
  
7	
                  Is	
  
      ,000 	
  AP                 tor ies	
  
 6
               	
  new      s	
  ...
Why does having
  a great API
    matter?
API growth rate
Based 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 ...
Apps & devices everywhere
5 Keys to a Great API
       Valuable
       Planned
       Flexible
       Managed
      Supported
5 Keys to a Great API
A 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)
ET #1
      I SECR
A   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 SECR
A   P

A very valuable service
 hides many API sins
the API Value Corollary
        The API value corollary



               A great API on a bad service
               is l...
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 choices
What 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:...
SOAP                                             REST
POST	
  /GetStock	
  HTTP/1.1	
                      GET	
  h@p://ex...
API protocols and styles
Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
ET #3
      I SECR
A   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...
What’s the price of IBM?
{	
                                       <?xml	
  version="1.0"?>	
  
	
  	
  	
  	
  "symbol":	...
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
    ...
API simplicity continuum


Simple                               Complex



  “As simple as possible, but no simpler”
What makes an API flexible?
             Provides choices
        data format, protocol, version

         Gives developer...
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
                                              Go...
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...
API versioning in REST
Where	
                        What	
               Who	
            Example	
  
Path	
  segment	
 ...
ET #4
      I SECR
A   P

It matters less how you
   version than you do
         version
API security baseline
Today:
SSL as option
OAuth 2.0 (one of the few API standards with traction)
Future:
SSL required (ma...
Great APIs get measured
       Great APIs get measured
Metrics that matter
 Traffic            Developers          Service
                     Total developers    Performance
 ...
ET #5
      I SECR
A   P

    Great APIs prioritize
     what they want to
          measure
“The absence of
limitations 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, pricin...
developerexperience.org

                see also
developer-support-handbook.appspot.com
ET #6
      I SECR
A   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 great
open APIs and open source
5 Keys to a Great API
       Valuable e	
  
              e	
  m or
 A nd     on
      	
  Planned
    ing     …	
  
     ...
Top 10 API worst practices
  10. Poor error handing
  9. REST APIs that ignore HTTP rules
  8. Exposing your raw underlyin...
#7
    P I SECR   ET     A great API
A
                     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/phot...
Upcoming SlideShare
Loading in …5
×

of

What Makes a Great Open API? Slide 1 What Makes a Great Open API? Slide 2 What Makes a Great Open API? Slide 3 What Makes a Great Open API? Slide 4 What Makes a Great Open API? Slide 5 What Makes a Great Open API? Slide 6 What Makes a Great Open API? Slide 7 What Makes a Great Open API? Slide 8 What Makes a Great Open API? Slide 9 What Makes a Great Open API? Slide 10 What Makes a Great Open API? Slide 11 What Makes a Great Open API? Slide 12 What Makes a Great Open API? Slide 13 What Makes a Great Open API? Slide 14 What Makes a Great Open API? Slide 15 What Makes a Great Open API? Slide 16 What Makes a Great Open API? Slide 17 What Makes a Great Open API? Slide 18 What Makes a Great Open API? Slide 19 What Makes a Great Open API? Slide 20 What Makes a Great Open API? Slide 21 What Makes a Great Open API? Slide 22 What Makes a Great Open API? Slide 23 What Makes a Great Open API? Slide 24 What Makes a Great Open API? Slide 25 What Makes a Great Open API? Slide 26 What Makes a Great Open API? Slide 27 What Makes a Great Open API? Slide 28 What Makes a Great Open API? Slide 29 What Makes a Great Open API? Slide 30 What Makes a Great Open API? Slide 31 What Makes a Great Open API? Slide 32 What Makes a Great Open API? Slide 33 What Makes a Great Open API? Slide 34 What Makes a Great Open API? Slide 35 What Makes a Great Open API? Slide 36 What Makes a Great Open API? Slide 37 What Makes a Great Open API? Slide 38 What Makes a Great Open API? Slide 39 What Makes a Great Open API? Slide 40 What Makes a Great Open API? Slide 41 What Makes a Great Open API? Slide 42 What Makes a Great Open API? Slide 43 What Makes a Great Open API? Slide 44 What Makes a Great Open API? Slide 45 What Makes a Great Open API? Slide 46 What Makes a Great Open API? Slide 47 What Makes a Great Open API? Slide 48 What Makes a Great Open API? Slide 49 What Makes a Great Open API? Slide 50 What Makes a Great Open API? Slide 51 What Makes a Great Open API? Slide 52 What Makes a Great Open API? Slide 53 What Makes a Great Open API? Slide 54 What Makes a Great Open API? Slide 55 What Makes a Great Open API? Slide 56 What Makes a Great Open API? Slide 57 What Makes a Great Open API? Slide 58 What Makes a Great Open API? Slide 59 What Makes a Great Open API? Slide 60 What Makes a Great Open API? Slide 61 What Makes a Great Open API? Slide 62 What Makes a Great Open API? Slide 63 What Makes a Great Open API? Slide 64 What Makes a Great Open API? Slide 65 What Makes a Great Open API? Slide 66 What Makes a Great Open API? Slide 67 What Makes a Great Open API? Slide 68 What Makes a Great Open API? Slide 69 What Makes a Great Open API? Slide 70 What Makes a Great Open API? Slide 71 What Makes a Great Open API? Slide 72
Upcoming SlideShare
API Business Models
Next
Download to read offline and view in fullscreen.

232 Likes

Share

Download to read offline

What Makes a Great Open API?

Download to read offline

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

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

What Makes a Great Open API?

  1. What Makes a Great 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 rate Based 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 rate Based 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 API A valuable service (data, function, audience, ) … A plan and a business model Simple, 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 SECR A 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 SECR A P A 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 choices 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. 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 REST 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>  
  28. API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
  29. ET #3 I SECR A 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 continuum Simple 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 console Twilio’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 REST Where   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 SECR A P It matters less how you version than you do version
  55. API security baseline Today: SSL as option OAuth 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 Retention Marketing Support Business Dev registrations Direct revenue Support tickets Indirect revenue Dev portal funnel Response times Market share Traffic sources Community metrics Costs Event metrics
  58. ET #5 I SECR A P Great APIs prioritize what they want to measure
  59. “The absence of limitations 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 also developer-support-handbook.appspot.com
  64. ET #6 I SECR A 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 great open 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 API A 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/      
  • KellyJones764721

    Nov. 27, 2021
  • tsubasakikuchi

    Sep. 7, 2021
  • GnanaSekhar4

    May. 29, 2020
  • rboneplus

    May. 6, 2020
  • PaulusJrLz

    Feb. 22, 2020
  • JulianMacagno

    Jan. 31, 2020
  • andreasfrankhoffmann

    Oct. 6, 2019
  • DarylYeoh1

    Sep. 3, 2019
  • daystory

    Jan. 31, 2019
  • jcunniet

    Nov. 21, 2018
  • brodellis

    May. 5, 2018
  • Wavyx

    Nov. 13, 2017
  • kemaltbayramoglu

    Nov. 7, 2017
  • joobn

    Oct. 18, 2017
  • cunniet1

    Oct. 18, 2017
  • rafaelcba

    Sep. 28, 2017
  • netflick

    Aug. 15, 2017
  • PianpianCarolynXu

    Aug. 6, 2017
  • DiegoManocchioPMPCIS

    Jul. 15, 2017
  • ChhorVeyHong

    Jun. 8, 2017

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

Views

Total views

120,847

On Slideshare

0

From embeds

0

Number of embeds

29,034

Actions

Downloads

1,859

Shares

0

Comments

0

Likes

232

×