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

▶
10 reasons developers
SMART_READER_LITE
LIVE PREVIEW

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

Oct 02, 2023 7 likes •810 views

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

slide-1
SLIDE 1

10 Reasons Developers Hate Your API

(and what to do about it)

John ¡Musser ¡@johnmusser ¡ ¡/ ¡ ¡API ¡Science ¡@apiscience ¡ QCon ¡NYC, ¡2014 ¡

slide-2
SLIDE 2

(private ¡beta) ¡

slide-3
SLIDE 3
slide-4
SLIDE 4
slide-5
SLIDE 5
slide-6
SLIDE 6

Your documentation sucks

R E A S O N # 1

slide-7
SLIDE 7

I S S U E S

Static Unloved No getting started Inaccurate Unprofessional Incomplete Out of date

slide-8
SLIDE 8

Big picture

https://www.twilio.com/docs

F I X # 1

slide-9
SLIDE 9

Clarity

https://stripe.com/docs/api

F I X # 2

slide-10
SLIDE 10

Find-ability

https://stripe.com/docs/

F I X # 3

slide-11
SLIDE 11

Live Docs

F I X # 4

Interactive documentation, like...

slide-12
SLIDE 12

Swagger

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

slide-13
SLIDE 13

I/O Docs

https://github.com/mashery/iodocs

slide-14
SLIDE 14

RAML

RESTful API Modeling Language raml.org

slide-15
SLIDE 15

Your communication skills need work

R E A S O N # 2

slide-16
SLIDE 16

You don’t keep your developers informed

R E A S O N # 2 B

slide-17
SLIDE 17

I S S U E S

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

slide-18
SLIDE 18

Change Log

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

F I X # 1

slide-19
SLIDE 19

Roadmap

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

F I X # 2

slide-20
SLIDE 20

Release Notes

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

F I X # 3

slide-21
SLIDE 21

Blog

http://aws.typepad.com/

F I X # 4

slide-22
SLIDE 22

Forum

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

F I X # 5

slide-23
SLIDE 23

Email

F I X # 6

slide-24
SLIDE 24

You don’t make it easy

R E A S O N # 3

slide-25
SLIDE 25

I S S U E S

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

slide-26
SLIDE 26

What do you do?

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

F I X # 1

slide-27
SLIDE 27

Fast signup

https://manage.stripe.com/register

F I X # 2

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

slide-28
SLIDE 28

The 1-2-3

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

F I X # 3

slide-29
SLIDE 29

Quickstarts

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

F I X # 4

slide-30
SLIDE 30

Free & Trial

https://parse.com/plans

F I X # 5

slide-31
SLIDE 31

Copious SDKs

F I X # 6

slide-32
SLIDE 32

Use GitHub

https://github.com/OneNoteDev

F I X # 7

slide-33
SLIDE 33

Lawyers

R E A S O N # 4

slide-34
SLIDE 34

I S S U E S

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

slide-35
SLIDE 35

Be clear

F I X # 1

http://500px.com/terms

slide-36
SLIDE 36

Set the tone

F I X # 2

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

slide-37
SLIDE 37

Shorter = Better

F I X # 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 ¡ …” ¡

slide-38
SLIDE 38

Page ¡23 ¡

slide-39
SLIDE 39

Think long term

F I X # 4

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

slide-40
SLIDE 40

Share the wealth

http://slideshare.net/jmusser

F I X # 5

slide-41
SLIDE 41

Your API is unreliable

R E A S O N # 5

slide-42
SLIDE 42

Your API is slow, buggy and unreliable

R E A S O N # 5

slide-43
SLIDE 43

I S S U E S

Bugs Unannounced changes Performance issues API outages Inconsistency

slide-44
SLIDE 44

Change (planned) Bug Outage

APIs can break

Rate limit ToS violation Change (undocumented) Provider biz change Network

slide-45
SLIDE 45

Breaking bad

slide-46
SLIDE 46

Don’t let this happen to you

GET http://api.yourcompany.com/resource/142

slide-47
SLIDE 47

Or this…

GET http://api.yourcompany.com/resource/142

slide-48
SLIDE 48

Status Page

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

F I X # 1

slide-49
SLIDE 49

Monitor

F I X # 2

http://www.apiscience.com

slide-50
SLIDE 50

Don’t hide

http://blog.akismet.com

F I X # 3

slide-51
SLIDE 51

You don’t give me the tools to help me succeed

R E A S O N # 6

slide-52
SLIDE 52

I S S U E S

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

slide-53
SLIDE 53

Dev Dashboard

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

F I X # 1

slide-54
SLIDE 54

Debug / Log

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

F I X # 2

slide-55
SLIDE 55

Test Sandbox

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

F I X # 3

slide-56
SLIDE 56

Playground

https://developers.google.com/oauthplayground

F I X # 4

slide-57
SLIDE 57

Test Console

https://apigee.com/providers

F I X # 5

slide-58
SLIDE 58

You’re marketing to me, not helping me

R E A S O N # 7

slide-59
SLIDE 59

I S S U E S

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

slide-60
SLIDE 60

Evangelists

http://sendgrid.com/developers

F I X # 1

slide-61
SLIDE 61

Events

F I X # 2

https://www.twilio.com/conference

slide-62
SLIDE 62

Hackathons

F I X # 3

slide-63
SLIDE 63

Your API is too complex

R E A S O N # 8

slide-64
SLIDE 64

You have your own customs

(auth, protocol, formats)

R E A S O N # 8 B

slide-65
SLIDE 65

I S S U E S

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

slide-66
SLIDE 66

Use REST

F I X # 1 API protocols and styles

Based on directory of 5,100 web APIs listed at ProgrammableWeb, February 2012

slide-67
SLIDE 67

Use JSON

F I X # 2 Percentage of APIs supporting JSON vs XML

Based on directory 11,000 web APIs listed at ProgrammableWeb, Dec 2013

slide-68
SLIDE 68

XML vs. JSON in new APIs

Based on new APIs listed at ProgrammableWeb in 2013

slide-69
SLIDE 69

Be pragmatic

F I X # 3

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

Web API Design, Brian Mulloy

slide-70
SLIDE 70

Your TTFHW is too long

R E A S O N # 9

slide-71
SLIDE 71

What’s your TTFHW?

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

slide-72
SLIDE 72

Great DX

F I X # 1

http://developerexperience.org

slide-73
SLIDE 73

F I X # 2

All prior “fixes” in this talk :-)

slide-74
SLIDE 74

You haven’t learned

R E A S O N # 1

slide-75
SLIDE 75

You haven’t learned (from the best)

R E A S O N # 1

slide-76
SLIDE 76

Use role models

F I X # 1

Twilio, Stripe, GitHub, SendGrid

slide-77
SLIDE 77

Keep learning

F I X # 2

apidays.io ¡ apistrategyconference.com ¡ www.gluecon.com ¡ apicon.programmableweb.com ¡ iloveapis2013.com ¡ apiconference.com ¡ www.qconferences.com ¡

slide-78
SLIDE 78

F I X # 3

Remember: An API is a journey, not a destination

slide-79
SLIDE 79

Thank You

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

slide-80
SLIDE 80

Photo ¡credits ¡

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