Ten Reasons Developers Hate Your API

80

Click here to load reader

Transcript of Ten Reasons Developers Hate Your API

Page 1: Ten Reasons Developers Hate Your API

10 Reasons Developers Hate Your API

(and what to do about it)

John  Musser  @johnmusser    /    API  Science  @apiscience  GlueCon,  2014  

Page 2: Ten Reasons Developers Hate Your API

(private  beta)  

Page 3: Ten Reasons Developers Hate Your API
Page 4: Ten Reasons Developers Hate Your API
Page 5: Ten Reasons Developers Hate Your API
Page 6: Ten Reasons Developers Hate Your API

Your documentation

sucks

REASON #1

Page 7: Ten Reasons Developers Hate Your API

ISSUES

Static

Unloved

No getting started

Inaccurate

Unprofessional

Incomplete

Out of date

Page 8: Ten Reasons Developers Hate Your API

Big picture

https://www.twilio.com/docs!

FIX #1

Page 9: Ten Reasons Developers Hate Your API

Clarity

https://stripe.com/docs/api!

FIX #2

Page 10: Ten Reasons Developers Hate Your API

Find-ability

https://stripe.com/docs/!

FIX #3

Page 11: Ten Reasons Developers Hate Your API

Live Docs FIX #4

Interactive documentation, like...

Page 12: Ten Reasons Developers Hate Your API

Swagger

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

Page 13: Ten Reasons Developers Hate Your API

I/O Docs

https://github.com/mashery/iodocs!

Page 14: Ten Reasons Developers Hate Your API

RAML

RESTful API Modeling Language!raml.org!

Page 15: Ten Reasons Developers Hate Your API

Your communication skills need work

REASON #2

Page 16: Ten Reasons Developers Hate Your API

You don’t keep your developers

informed

REASON #2B

Page 17: Ten Reasons Developers Hate Your API

ISSUES

Where do I get support again?

Too many/few channels

Infrequent communication

You broke my code without warning

Page 18: Ten Reasons Developers Hate Your API

Change Log

http://developer.github.com/changes/!

FIX #1

Page 19: Ten Reasons Developers Hate Your API

Roadmap

https://developers.facebook.com/roadmap/!

FIX #2

Page 20: Ten Reasons Developers Hate Your API

Release Notes

http://techblog.constantcontact.com/api/release-updates!

FIX #3

Page 21: Ten Reasons Developers Hate Your API

Blog

http://aws.typepad.com/!

FIX #4

Page 22: Ten Reasons Developers Hate Your API

Forum

http://stackoverflow.com/questions/tagged/soundcloud!

FIX #5

Page 23: Ten Reasons Developers Hate Your API

Email FIX #6

Page 24: Ten Reasons Developers Hate Your API

You don’t make it easy

REASON #3

Page 25: Ten Reasons Developers Hate Your API

ISSUES

How do I get my keys?

No getting started guide

No SDKs / samples in my language

Nothing to copy & paste…

No “hello world”

Page 26: Ten Reasons Developers Hate Your API

What do you do?

https://www.twilio.com/voice/api!

FIX #1

Page 27: Ten Reasons Developers Hate Your API

Fast signup

https://manage.stripe.com/register!

FIX #2

(so fast, you can even skip this step till you’re convinced…)

Page 28: Ten Reasons Developers Hate Your API

The 1-2-3

http://developer.constantcontact.com/get-started.html!

FIX #3

Page 29: Ten Reasons Developers Hate Your API

Quickstarts

https://www.twilio.com/docs/quickstart!

FIX #4

Page 30: Ten Reasons Developers Hate Your API

Free & Trial

https://parse.com/plans!

FIX #5

Page 31: Ten Reasons Developers Hate Your API

Copious SDKs FIX #6

Page 32: Ten Reasons Developers Hate Your API

Use GitHub

https://github.com/OneNoteDev!

FIX #7

Page 33: Ten Reasons Developers Hate Your API

Lawyers REASON #4

Page 34: Ten Reasons Developers Hate Your API

ISSUES

Commercial restrictions Not setup for win-win

No SLA

Rate limit / throttling issues

It’s all about you

Page 35: Ten Reasons Developers Hate Your API

Be clear FIX #1

http://500px.com/terms!

Page 36: Ten Reasons Developers Hate Your API

Set the tone FIX #2

https://www.etsy.com/developers/terms-of-use!

Page 37: Ten Reasons Developers Hate Your API

Shorter = Better FIX #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  …”  

Page 38: Ten Reasons Developers Hate Your API

Page  23  

Page 39: Ten Reasons Developers Hate Your API

Think long term FIX #4

https://developers.google.com/youtube/terms!

Page 40: Ten Reasons Developers Hate Your API

Share the wealth

http://slideshare.net/jmusser!

FIX #5

Page 41: Ten Reasons Developers Hate Your API

Your API is unreliable

REASON #5

Page 42: Ten Reasons Developers Hate Your API

Your API is slow, buggy and

unreliable

REASON #5

Page 43: Ten Reasons Developers Hate Your API

ISSUES

Bugs

Unannounced changes

Performance issues

API outages

Inconsistency

Page 44: Ten Reasons Developers Hate Your API

Change (planned)

Bug Outage

APIs can break

Rate limit

ToS violation

Change (undocumented)

Provider biz change Network

Page 45: Ten Reasons Developers Hate Your API

Breaking bad

Page 46: Ten Reasons Developers Hate Your API

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

Page 47: Ten Reasons Developers Hate Your API

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

Page 48: Ten Reasons Developers Hate Your API

Status Page

http://status.aws.amazon.com/!

FIX #1

Page 49: Ten Reasons Developers Hate Your API

Monitor FIX #2

http://www.apiscience.com!

Page 50: Ten Reasons Developers Hate Your API

Don’t hide

http://blog.akismet.com!

FIX #3

Page 51: Ten Reasons Developers Hate Your API

You don’t give me the tools to help

me succeed

REASON #6

Page 52: Ten Reasons Developers Hate Your API

ISSUES

Test console?

OAuth, ouch

How do I debug?

What’s my usage? Spend?

Page 53: Ten Reasons Developers Hate Your API

Dev Dashboard

https://manage.stripe.com/test/dashboard!

FIX #1

Page 54: Ten Reasons Developers Hate Your API

Debug / Log

www.twilio.com/user/account/developer-tools/app-monitor!

FIX #2

Page 55: Ten Reasons Developers Hate Your API

Test Sandbox

https://www.twilio.com/user/account!

FIX #3

Page 56: Ten Reasons Developers Hate Your API

Playground

https://developers.google.com/oauthplayground!

FIX #4

Page 57: Ten Reasons Developers Hate Your API

Test Console

https://apigee.com/providers!

FIX #5

Page 58: Ten Reasons Developers Hate Your API

You’re marketing to me,

not helping me

REASON #7

Page 59: Ten Reasons Developers Hate Your API

ISSUES

You don’t listen

Code, not whitepapers

Developers hate marketing

Self-service, not “call us”

Page 60: Ten Reasons Developers Hate Your API

Evangelists

http://sendgrid.com/developers!

FIX #1

Page 61: Ten Reasons Developers Hate Your API

Events FIX #2

https://www.twilio.com/conference!

Page 62: Ten Reasons Developers Hate Your API

Hackathons FIX #3

Page 63: Ten Reasons Developers Hate Your API

Your API is too complex

REASON #8

Page 64: Ten Reasons Developers Hate Your API

You have your own customs

(auth, protocol, formats)

REASON #8B

Page 65: Ten Reasons Developers Hate Your API

ISSUES

Terse, cryptic error messages

No JSON support

Your “REST” API doesn’t use HTTP rules

You still use SOAP

Page 66: Ten Reasons Developers Hate Your API

Use REST FIX #1

API protocols and styles Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012

Page 67: Ten Reasons Developers Hate Your API

Use JSON FIX #2

Percentage of APIs supporting JSON vs XML Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec 2013

Page 68: Ten Reasons Developers Hate Your API

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

Page 69: Ten Reasons Developers Hate Your API

Be pragmatic FIX #3

http://apigee.com/about/content/web-api-design!

Web API Design, Brian Mulloy

Page 70: Ten Reasons Developers Hate Your API

Your TTFHW is too long

REASON #9

Page 71: Ten Reasons Developers Hate Your API

What’s your TTFHW?

Time To First “Hello World” aka: how long from zero to 60?

Page 72: Ten Reasons Developers Hate Your API

Great DX FIX #1

http://developerexperience.org!

Page 73: Ten Reasons Developers Hate Your API

FIX #2

All prior “fixes”

in this talk :-)

Page 74: Ten Reasons Developers Hate Your API

You haven’t learned

REASON #10

Page 75: Ten Reasons Developers Hate Your API

You haven’t learned

(from the best)

REASON #10

Page 76: Ten Reasons Developers Hate Your API

Use role models FIX #1

Twilio, Stripe, Github, SendGrid

Page 77: Ten Reasons Developers Hate Your API

Keep learning FIX #2

apidays.io  apistrategyconference.com  www.gluecon.com  

apicon.programmableweb.com  iloveapis2013.com   apiconference.com  

Page 78: Ten Reasons Developers Hate Your API

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

Page 79: Ten Reasons Developers Hate Your API

Thank You

QuesMons,  ideas,  [email protected]  

@johnmusser    

Page 80: Ten Reasons Developers Hate Your API

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