10 Reasons Developers Hate Your API (and what to do about it) John - PowerPoint PPT Presentation

10 Reasons Developers Hate Your API (and what to do about it) John ¡Musser ¡@johnmusser ¡ ¡/ ¡ ¡API ¡Science ¡@apiscience ¡ QCon ¡NYC, ¡2014 ¡

(private ¡beta) ¡

1 # N O S A E R Your documentation sucks

S E U S S I Out of date Inaccurate Incomplete No getting started Static Unprofessional Unloved

Big picture 1 # X I F https://www.twilio.com/docs �

Clarity 2 # X I F https://stripe.com/docs/api �

Find-ability 3 # X I F https://stripe.com/docs/ �

Live Docs 4 # X I F Interactive documentation, like...

Swagger https://github.com/wordnik/swagger-core �

I/O Docs https://github.com/mashery/iodocs �

RAML RESTful API Modeling Language � raml.org �

2 # N O S A E R Your communication skills need work

B 2 # N O S A E R You don’t keep your developers informed

S E U S S I Infrequent communication You broke my code without warning Too many/few channels Where do I get support again?

Change Log 1 # X I F http://developer.github.com/changes/ �

Roadmap 2 # X I F https://developers.facebook.com/roadmap/ �

Release Notes 3 # X I F http://techblog.constantcontact.com/api/release-updates �

Blog 4 # X I F http://aws.typepad.com/ �

Forum 5 # X I F http://stackoverflow.com/questions/tagged/soundcloud �

Email 6 # X I F

3 # N O S A E R You don’t make it easy

S E U S No “hello world” S I No getting started guide How do I get my keys? No SDKs / samples in my language Nothing to copy & paste…

What do you do? 1 # X I F https://www.twilio.com/voice/api �

Fast signup 2 # X I F (so fast, you can even skip this step till you’re convinced…) https://manage.stripe.com/register �

The 1-2-3 3 # X I F http://developer.constantcontact.com/get-started.html �

Quickstarts 4 # X I F https://www.twilio.com/docs/quickstart �

Free & Trial 5 # X I F https://parse.com/plans �

Copious SDKs 6 # X I F

Use GitHub 7 # X I F https://github.com/OneNoteDev �

4 # N O S A E R Lawyers

S E U S S I It’s all about you Not setup for win-win Commercial restrictions No SLA Rate limit / throttling issues

Be clear 1 # X I F http://500px.com/terms �

Set the tone 2 # X I F https://www.etsy.com/developers/terms-of-use �

Shorter = Better 3 # X I F “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 ¡ …” ¡ http://googledevelopers.blogspot.com �

Page ¡23 ¡

Think long term 4 # X I F https://developers.google.com/youtube/terms �

Share the wealth 5 # X I F http://slideshare.net/jmusser �

5 # N O S A E R Your API is unreliable

5 # N O S A E R Your API is slow, buggy and unreliable

S E U S S I API outages Unannounced changes Bugs Performance issues Inconsistency

APIs can break Outage Bug Rate limit Change Change ( planned ) ( undocumented ) Provider biz ToS violation Network change

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 � �

Status Page 1 # X I F http://status.aws.amazon.com/ �

Monitor 2 # X I F http://www.apiscience.com �

Don’t hide 3 # X I F http://blog.akismet.com �

6 # N O S A E R You don’t give me the tools to help me succeed

S E U S S I How do I debug? What’s my usage? Spend? OAuth, ouch Test console?

Dev Dashboard 1 # X I F https://manage.stripe.com/test/dashboard �

Debug / Log 2 # X I F www.twilio.com/user/account/developer-tools/app-monitor �

Test Sandbox 3 # X I F https://www.twilio.com/user/account �

Playground 4 # X I F https://developers.google.com/oauthplayground �

Test Console 5 # X I F https://apigee.com/providers �

7 # N O S A E R You’re marketing to me, not helping me

S E U S S I Self-service, not “call us” Code, not whitepapers You don’t listen Developers hate marketing

Evangelists 1 # X I F http://sendgrid.com/developers �

Events 2 # X I F https://www.twilio.com/conference �

Hackathons 3 # X I F

8 # N O S A E R Your API is too complex

B 8 # N O S A E R You have your own customs (auth, protocol, formats)

S E U S S I You still use SOAP No JSON support Terse, cryptic error messages Your “REST” API doesn’t use HTTP rules

Use REST 1 # X I F API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012

Use JSON 2 # X I F Percentage of APIs supporting JSON vs XML Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec 2013

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

Be pragmatic 3 # X I F Web API Design, Brian Mulloy http://apigee.com/about/content/web-api-design �

9 # N O S A E R Your TTFHW is too long

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

Great DX 1 # X I F http://developerexperience.org �

2 # X I F All prior “fixes” in this talk :-)

0 1 # N O S A E R You haven’t learned

0 1 # N O S A E R You haven’t learned (from the best)

Use role models 1 # X I F Twilio, Stripe, GitHub, SendGrid

Keep learning 2 # X I F www.qconferences.com ¡ www.gluecon.com ¡ apistrategyconference.com ¡ apidays.io ¡ iloveapis2013.com ¡ apicon.programmableweb.com ¡ apiconference.com ¡

3 Remember: # X I F An API is a journey, not a destination

Thank You QuesNons, ¡ideas, ¡comments? john@apiscience.com ¡ @johnmusser ¡ ¡

Photo ¡credits ¡ Race ¡car: ¡hRp://www.flickr.com/photos/lim_lik_wei/3270522646/ ¡ Winding ¡road: ¡hRp://www.flickr.com/photos/maRhewthecoolguy/7518274258/ ¡ ¡ ¡