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.
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....
What’s your TTFHW? Time To
What’s your TTFHW? Time To
What’s your TTFHW? Time To
Upcoming SlideShare
Loading in …5
×

What’s your TTFHW? Time To Ten Reasons Developers Hate Your API

118,740 views

Published on

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

Published in: Internet, Technology, Design

×