0
10ReasonsDevelopers
HateYourAPI
(andwhattodoaboutit)
John	
  Musser	
  @johnmusser	
  	
  /	
  	
  API	
  Science	
  @apis...
(private	
  beta)	
  
Your
documentation
sucks
REASON #1
ISSUES
Static
Unloved
Nogettingstarted
Inaccurate
Unprofessional
Incomplete
Outofdate
Bigpicture
https://www.twilio.com/docs!
FIX #1
Clarity
https://stripe.com/docs/api!
FIX #2
Find-ability
https://stripe.com/docs/!
FIX #3
LiveDocsFIX #4
Interactivedocumentation,
like...
Swagger
https://github.com/wordnik/swagger-core!
I/ODocs
https://github.com/mashery/iodocs!
RAML
RESTful API Modeling Language!
raml.org!
Yourcommunication
skillsneedwork
REASON #2
Youdon’tkeep
yourdevelopers
informed
REASON #2B
ISSUES
WheredoIgetsupportagain?
Toomany/fewchannels
Infrequentcommunication
Youbrokemycodewithoutwarning
ChangeLog
http://developer.github.com/changes/!
FIX #1
Roadmap
https://developers.facebook.com/roadmap/!
FIX #2
ReleaseNotes
http://techblog.constantcontact.com/api/release-updates!
FIX #3
Blog
http://aws.typepad.com/!
FIX #4
Forum
http://stackoverflow.com/questions/tagged/soundcloud!
FIX #5
EmailFIX #6
Youdon’t
makeiteasy
REASON #3
ISSUES
HowdoIgetmykeys?
Nogettingstartedguide
NoSDKs/samplesinmylanguage
Nothingtocopy&paste…
No“helloworld”
Whatdoyoudo?
https://www.twilio.com/voice/api!
FIX #1
Fastsignup
https://manage.stripe.com/register!
FIX #2
(so fast, you can even skip this
step till you’re convinced…)
The1-2-3
http://developer.constantcontact.com/get-started.html!
FIX #3
Quickstarts
https://www.twilio.com/docs/quickstart!
FIX #4
Free&Trial
https://parse.com/plans!
FIX #5
CopiousSDKsFIX #6
UseGitHub
https://github.com/OneNoteDev!
FIX #7
Lawyers
REASON #4
ISSUES
Commercialrestrictions
Notsetupforwin-win
NoSLA
Ratelimit/throttlingissues
It’sallaboutyou
BeclearFIX #1
http://500px.com/terms!
SetthetoneFIX #2
https://www.etsy.com/developers/terms-of-use!
Shorter=BetterFIX #3
http://googledevelopers.blogspot.com!
“Beginning	
  today,	
  most	
  of	
  our	
  APIs	
  use	
  a	
...
Page	
  23	
  
ThinklongtermFIX #4
https://developers.google.com/youtube/terms!
Sharethewealth
http://slideshare.net/jmusser!
FIX #5
YourAPIis
unreliable
REASON #5
YourAPIis
slow,buggyand
unreliable
REASON #5
ISSUES
Bugs
Unannouncedchanges
Performanceissues
APIoutages
Inconsistency
Change
(planned)
BugOutage
APIs can break
Rate limit
ToS violation
Change
(undocumented)
Provider biz
change
Network
Breaking bad
Don’t let this happen to you
GET http://api.yourcompany.com/resource/142!
!
Or this…
GET http://api.yourcompany.com/resource/142!
!
StatusPage
http://status.aws.amazon.com/!
FIX #1
MonitorFIX #2
http://www.apiscience.com!
Don’thide
http://blog.akismet.com!
FIX #3
Youdon’tgiveme
thetoolstohelp
mesucceed
REASON #6
ISSUES
Testconsole?
OAuth,ouch
HowdoIdebug?
What’smyusage?Spend?
DevDashboard
https://manage.stripe.com/test/dashboard!
FIX #1
Debug/Log
www.twilio.com/user/account/developer-tools/app-monitor!
FIX #2
TestSandbox
https://www.twilio.com/user/account!
FIX #3
Playground
https://developers.google.com/oauthplayground!
FIX #4
TestConsole
https://apigee.com/providers!
FIX #5
You’remarketing
tome,
nothelpingme
REASON #7
ISSUES
Youdon’tlisten
Code,notwhitepapers
Developershatemarketing
Self-service,not“callus”
Evangelists
http://sendgrid.com/developers!
FIX #1
EventsFIX #2
https://www.twilio.com/conference!
HackathonsFIX #3
YourAPIistoo
complex
REASON #8
Youhaveyourown
customs
(auth,protocol,formats)
REASON #8B
ISSUES
Terse,crypticerrormessages
NoJSONsupport
Your“REST”APIdoesn’tuseHTTPrules
YoustilluseSOAP
UseRESTFIX #1
API protocols and styles
Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
UseJSONFIX #2
Percentage of APIs supporting JSON vs XML
Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec ...
XML vs. JSON in new APIs
Based on new APIs listed at ProgrammableWeb in 2013
BepragmaticFIX #3
http://apigee.com/about/content/web-api-design!
Web API Design,
Brian Mulloy
YourTTFHW
istoolong
REASON #9
What’s your TTFHW?
Time To First “Hello World”
aka: how long from zero to 60?
GreatDXFIX #1
http://developerexperience.org!
FIX #2
Allprior
“fixes”
inthistalk:-)
Youhaven’t
learned
REASON #10
Youhaven’t
learned
(fromthebest)
REASON #10
UserolemodelsFIX #1
Twilio,Stripe,Github,
SendGrid
KeeplearningFIX #2
apidays.io	
  apistrategyconference.com	
  
www.gluecon.com	
  
apicon.programmableweb.com	
  iloveapis...
FIX #3
Remember:
An API is a journey,
not a destination
Thank You
QuesMons,	
  ideas,	
  comments?
john@apiscience.com	
  
@johnmusser	
  
	
  
Photo	
  credits	
  
Race	
  car:	
  hQp://www.flickr.com/photos/lim_lik_wei/3270522646/	
  
Winding	
  road:	
  hQp://www....
Ten Reasons Developers Hate Your API
Ten Reasons Developers Hate Your API
Ten Reasons Developers Hate Your API
Prochain SlideShare
Chargement dans... 5
×

Ten Reasons Developers Hate Your API

63,992

Published on

APIs are everywhere today and can be a great building block of modern applications. But all too often APIs are not truly great. Rather than love your API, developers curse it. How can you avoid that fate? In this session we'll look at the most common mistakes API providers make and you can avoid making them too. Do you offer a bad developer experience (DX)? Poor, inconsistent API design? Unreliable services? This talk is a deep dive on not just what to avoid but what to do instead. And you'll leave knowing how to get developers to love your API, not hate it. 

Published in: Internet, Technologies, Design
11 commentaires
205 mentions J'aime
Statistiques
Remarques
Aucun téléchargement
Vues
Total des vues
63,992
Sur Slideshare
0
À partir des ajouts
0
Nombre d'ajouts
34
Actions
Partages
0
Téléchargements
930
Commentaires
11
J'aime
205
Ajouts 0
No embeds

No notes for slide

Transcript of "Ten Reasons Developers Hate Your API"

  1. 1. 10ReasonsDevelopers HateYourAPI (andwhattodoaboutit) John  Musser  @johnmusser    /    API  Science  @apiscience   GlueCon,  2014  
  2. 2. (private  beta)  
  3. 3. Your documentation sucks REASON #1
  4. 4. ISSUES Static Unloved Nogettingstarted Inaccurate Unprofessional Incomplete Outofdate
  5. 5. Bigpicture https://www.twilio.com/docs! FIX #1
  6. 6. Clarity https://stripe.com/docs/api! FIX #2
  7. 7. Find-ability https://stripe.com/docs/! FIX #3
  8. 8. LiveDocsFIX #4 Interactivedocumentation, like...
  9. 9. Swagger https://github.com/wordnik/swagger-core!
  10. 10. I/ODocs https://github.com/mashery/iodocs!
  11. 11. RAML RESTful API Modeling Language! raml.org!
  12. 12. Yourcommunication skillsneedwork REASON #2
  13. 13. Youdon’tkeep yourdevelopers informed REASON #2B
  14. 14. ISSUES WheredoIgetsupportagain? Toomany/fewchannels Infrequentcommunication Youbrokemycodewithoutwarning
  15. 15. ChangeLog http://developer.github.com/changes/! FIX #1
  16. 16. Roadmap https://developers.facebook.com/roadmap/! FIX #2
  17. 17. ReleaseNotes http://techblog.constantcontact.com/api/release-updates! FIX #3
  18. 18. Blog http://aws.typepad.com/! FIX #4
  19. 19. Forum http://stackoverflow.com/questions/tagged/soundcloud! FIX #5
  20. 20. EmailFIX #6
  21. 21. Youdon’t makeiteasy REASON #3
  22. 22. ISSUES HowdoIgetmykeys? Nogettingstartedguide NoSDKs/samplesinmylanguage Nothingtocopy&paste… No“helloworld”
  23. 23. Whatdoyoudo? https://www.twilio.com/voice/api! FIX #1
  24. 24. Fastsignup https://manage.stripe.com/register! FIX #2 (so fast, you can even skip this step till you’re convinced…)
  25. 25. The1-2-3 http://developer.constantcontact.com/get-started.html! FIX #3
  26. 26. Quickstarts https://www.twilio.com/docs/quickstart! FIX #4
  27. 27. Free&Trial https://parse.com/plans! FIX #5
  28. 28. CopiousSDKsFIX #6
  29. 29. UseGitHub https://github.com/OneNoteDev! FIX #7
  30. 30. Lawyers REASON #4
  31. 31. ISSUES Commercialrestrictions Notsetupforwin-win NoSLA Ratelimit/throttlingissues It’sallaboutyou
  32. 32. BeclearFIX #1 http://500px.com/terms!
  33. 33. SetthetoneFIX #2 https://www.etsy.com/developers/terms-of-use!
  34. 34. Shorter=BetterFIX #3 http://googledevelopers.blogspot.com! “Beginning  today,  most  of  our  APIs  use  a  single  Terms  of   Service.  We  have  rewri%en  these  terms  from  the  ground   up  with  the  goals  of  making  them  concise  and  easier  to   understand.     ….   In  this  rewrite,  we  have  removed  over  125,000  words   from  the  combined  previous  terms   …”  
  35. 35. Page  23  
  36. 36. ThinklongtermFIX #4 https://developers.google.com/youtube/terms!
  37. 37. Sharethewealth http://slideshare.net/jmusser! FIX #5
  38. 38. YourAPIis unreliable REASON #5
  39. 39. YourAPIis slow,buggyand unreliable REASON #5
  40. 40. ISSUES Bugs Unannouncedchanges Performanceissues APIoutages Inconsistency
  41. 41. Change (planned) BugOutage APIs can break Rate limit ToS violation Change (undocumented) Provider biz change Network
  42. 42. Breaking bad
  43. 43. Don’t let this happen to you GET http://api.yourcompany.com/resource/142! !
  44. 44. Or this… GET http://api.yourcompany.com/resource/142! !
  45. 45. StatusPage http://status.aws.amazon.com/! FIX #1
  46. 46. MonitorFIX #2 http://www.apiscience.com!
  47. 47. Don’thide http://blog.akismet.com! FIX #3
  48. 48. Youdon’tgiveme thetoolstohelp mesucceed REASON #6
  49. 49. ISSUES Testconsole? OAuth,ouch HowdoIdebug? What’smyusage?Spend?
  50. 50. DevDashboard https://manage.stripe.com/test/dashboard! FIX #1
  51. 51. Debug/Log www.twilio.com/user/account/developer-tools/app-monitor! FIX #2
  52. 52. TestSandbox https://www.twilio.com/user/account! FIX #3
  53. 53. Playground https://developers.google.com/oauthplayground! FIX #4
  54. 54. TestConsole https://apigee.com/providers! FIX #5
  55. 55. You’remarketing tome, nothelpingme REASON #7
  56. 56. ISSUES Youdon’tlisten Code,notwhitepapers Developershatemarketing Self-service,not“callus”
  57. 57. Evangelists http://sendgrid.com/developers! FIX #1
  58. 58. EventsFIX #2 https://www.twilio.com/conference!
  59. 59. HackathonsFIX #3
  60. 60. YourAPIistoo complex REASON #8
  61. 61. Youhaveyourown customs (auth,protocol,formats) REASON #8B
  62. 62. ISSUES Terse,crypticerrormessages NoJSONsupport Your“REST”APIdoesn’tuseHTTPrules YoustilluseSOAP
  63. 63. UseRESTFIX #1 API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012
  64. 64. UseJSONFIX #2 Percentage of APIs supporting JSON vs XML Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec 2013
  65. 65. XML vs. JSON in new APIs Based on new APIs listed at ProgrammableWeb in 2013
  66. 66. BepragmaticFIX #3 http://apigee.com/about/content/web-api-design! Web API Design, Brian Mulloy
  67. 67. YourTTFHW istoolong REASON #9
  68. 68. What’s your TTFHW? Time To First “Hello World” aka: how long from zero to 60?
  69. 69. GreatDXFIX #1 http://developerexperience.org!
  70. 70. FIX #2 Allprior “fixes” inthistalk:-)
  71. 71. Youhaven’t learned REASON #10
  72. 72. Youhaven’t learned (fromthebest) REASON #10
  73. 73. UserolemodelsFIX #1 Twilio,Stripe,Github, SendGrid
  74. 74. KeeplearningFIX #2 apidays.io  apistrategyconference.com   www.gluecon.com   apicon.programmableweb.com  iloveapis2013.com   apiconference.com  
  75. 75. FIX #3 Remember: An API is a journey, not a destination
  76. 76. Thank You QuesMons,  ideas,  comments? john@apiscience.com   @johnmusser    
  77. 77. Photo  credits   Race  car:  hQp://www.flickr.com/photos/lim_lik_wei/3270522646/   Winding  road:  hQp://www.flickr.com/photos/maQhewthecoolguy/7518274258/      
  1. A particular slide catching your eye?

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

×