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. 

1. 10ReasonsDevelopers
HateYourAPI
(andwhattodoaboutit)
John
Musser
@johnmusser
/
API
Science
@apiscience
GlueCon,
2014

2. (private
beta)

6. Your
documentation
sucks
REASON #1

7. ISSUES
Static
Unloved
Nogettingstarted
Inaccurate
Unprofessional
Incomplete
Outofdate

8. Bigpicture
https://www.twilio.com/docs!
FIX #1

9. Clarity
https://stripe.com/docs/api!
FIX #2

10. Find-ability
https://stripe.com/docs/!
FIX #3

11. LiveDocsFIX #4
Interactivedocumentation,
like...

12. Swagger
https://github.com/wordnik/swagger-core!

13. I/ODocs
https://github.com/mashery/iodocs!

14. RAML
RESTful API Modeling Language!
raml.org!

15. Yourcommunication
skillsneedwork
REASON #2

16. Youdon’tkeep
yourdevelopers
informed
REASON #2B

17. ISSUES
WheredoIgetsupportagain?
Toomany/fewchannels
Infrequentcommunication
Youbrokemycodewithoutwarning

18. ChangeLog
http://developer.github.com/changes/!
FIX #1

19. Roadmap
https://developers.facebook.com/roadmap/!
FIX #2

20. ReleaseNotes
http://techblog.constantcontact.com/api/release-updates!
FIX #3

21. Blog
http://aws.typepad.com/!
FIX #4

22. Forum
http://stackoverflow.com/questions/tagged/soundcloud!
FIX #5

23. EmailFIX #6

24. Youdon’t
makeiteasy
REASON #3

25. ISSUES
HowdoIgetmykeys?
Nogettingstartedguide
NoSDKs/samplesinmylanguage
Nothingtocopy&paste…
No“helloworld”

26. Whatdoyoudo?
https://www.twilio.com/voice/api!
FIX #1

27. Fastsignup
https://manage.stripe.com/register!
FIX #2
(so fast, you can even skip this
step till you’re convinced…)

28. The1-2-3
http://developer.constantcontact.com/get-started.html!
FIX #3

29. Quickstarts
https://www.twilio.com/docs/quickstart!
FIX #4

30. Free&Trial
https://parse.com/plans!
FIX #5

31. CopiousSDKsFIX #6

32. UseGitHub
https://github.com/OneNoteDev!
FIX #7

33. Lawyers
REASON #4

34. ISSUES
Commercialrestrictions
Notsetupforwin-win
NoSLA
Ratelimit/throttlingissues
It’sallaboutyou

35. BeclearFIX #1
http://500px.com/terms!

36. SetthetoneFIX #2
https://www.etsy.com/developers/terms-of-use!

37. 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
…”

38. Page
23

39. ThinklongtermFIX #4
https://developers.google.com/youtube/terms!

40. Sharethewealth
http://slideshare.net/jmusser!
FIX #5

41. YourAPIis
unreliable
REASON #5

42. YourAPIis
slow,buggyand
unreliable
REASON #5

43. ISSUES
Bugs
Unannouncedchanges
Performanceissues
APIoutages
Inconsistency

44. Change
(planned)
BugOutage
APIs can break
Rate limit
ToS violation
Change
(undocumented)
Provider biz
change
Network

45. Breaking bad

46. Don’t let this happen to you
GET http://api.yourcompany.com/resource/142!
!

47. Or this…
GET http://api.yourcompany.com/resource/142!
!

48. StatusPage
http://status.aws.amazon.com/!
FIX #1

49. MonitorFIX #2
http://www.apiscience.com!

50. Don’thide
http://blog.akismet.com!
FIX #3

51. Youdon’tgiveme
thetoolstohelp
mesucceed
REASON #6

52. ISSUES
Testconsole?
OAuth,ouch
HowdoIdebug?
What’smyusage?Spend?

53. DevDashboard
https://manage.stripe.com/test/dashboard!
FIX #1

54. Debug/Log
www.twilio.com/user/account/developer-tools/app-monitor!
FIX #2

55. TestSandbox
https://www.twilio.com/user/account!
FIX #3

56. Playground
https://developers.google.com/oauthplayground!
FIX #4

57. TestConsole
https://apigee.com/providers!
FIX #5

58. You’remarketing
tome,
nothelpingme
REASON #7

59. ISSUES
Youdon’tlisten
Code,notwhitepapers
Developershatemarketing
Self-service,not“callus”

60. Evangelists
http://sendgrid.com/developers!
FIX #1

61. EventsFIX #2
https://www.twilio.com/conference!

62. HackathonsFIX #3

63. YourAPIistoo
complex
REASON #8

64. Youhaveyourown
customs
(auth,protocol,formats)
REASON #8B

65. ISSUES
Terse,crypticerrormessages
NoJSONsupport
Your“REST”APIdoesn’tuseHTTPrules
YoustilluseSOAP

66. UseRESTFIX #1
API protocols and styles
Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012

67. UseJSONFIX #2
Percentage of APIs supporting JSON vs XML
Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec 2013

68. XML vs. JSON in new APIs
Based on new APIs listed at ProgrammableWeb in 2013

69. BepragmaticFIX #3
http://apigee.com/about/content/web-api-design!
Web API Design,
Brian Mulloy

70. YourTTFHW
istoolong
REASON #9

71. What’s your TTFHW?
Time To First “Hello World”
aka: how long from zero to 60?

72. GreatDXFIX #1
http://developerexperience.org!

73. FIX #2
Allprior
“fixes”
inthistalk:-)

74. Youhaven’t
learned
REASON #10

75. Youhaven’t
learned
(fromthebest)
REASON #10

76. UserolemodelsFIX #1
Twilio,Stripe,Github,
SendGrid

77. KeeplearningFIX #2
apidays.io
apistrategyconference.com
www.gluecon.com
apicon.programmableweb.com
iloveapis2013.com
apiconference.com

78. FIX #3
Remember:
An API is a journey,
not a destination

79. Thank You
QuesMons,
ideas,
comments?
john@apiscience.com
@johnmusser

80. Photo
credits
Race
car:
hQp://www.flickr.com/photos/lim_lik_wei/3270522646/
Winding
road:
hQp://www.flickr.com/photos/maQhewthecoolguy/7518274258/