10 things i hate about your api - scale...10 things i hate about your api amanda folson developer...

10 Things I Hate About Your APIAmanda Folson

Developer Advocate @ GitLab@AmbassadorAwsum

Who Am I?● Developer Advocate

@ GitLab● API Person● Tinkerer● Word maker

1) Your Onboarding Stinks

Is This Thing On?

● Signup takes too long

● Not easy to get started

● No sample code at all!

Onboarding Solutions

● Make signup a breeze● Get someone immersed in your

API in under 5 minutes● Measure Time To First $thing

○ Time to First Request○ Time to First API Key○ Time to First SMS○ Time to First Order

2) No Tools to Succeed

Tooling Problems

● No SDKs

● No quickstarts

● No sandbox for testing

● Nowhere to get help (???)

© Ian Baker (CC BY 2.0) https://www.flickr.com/photos/raindrift/7095238893/in/album-72157629492908038/

Tooling Solutions

● Provide SDKs or sample code

● Provide docs and sample apps to get started

● Provide a sandbox to play in

● Make it easy to get help if they’re stuck

3) Your Documentation Stinks

Documentation Problems

● Out of date or inaccurate

● Incomplete

● Not useful

Documentation Solutions

● Have docs

● Tools like Swagger/Apiary

● Add quickstarts and tutorials for people to play with

● Make documentation part of your API strategy

HelloSign Documentation

4) API is a Sales Tool instead of Success Tool

I’m just the developer...

Twilio Signup Form

Recap

● Don’t make me buy before I try

● Ideally I don’t have to wait for a human to set up my account

● Be careful where you put your Call to Actions

5) Your API Isn’t Reliable

uptime++;● Your uptime is awful

● Your responses are slow

● You don’t announce breaking changes

● There are too many bugs

● Too inconsistent (more on that later)

● Invest time to make sure your API is robust

● Stop making unannounced breaking changes

● Change logs!

● Invest time in designing your API

6) Your API is Poorly Designed

/lol/what● Endpoints make no sense

○ /users/1/orders -> View a user’s orders○ /orders/1/9001 -> View order 9001 which is owned by user 1

■ Users own orders, we could have:● /users/1/orders/● /users/1/orders/9001

● Endpoints have inconsistent data○ /users/1/ -> creation_date○ /orders/9001 -> created-date

Design First Approach

● Map out endpoints logically

○ I do this on paper

● Design for a uniform experience

7) Your API Doesn’t Meet Users’ Needs

Build Something People Want (or NEED)

● Your API is missing important features

● You don’t incorporate feedback

● You build for yourselves and not users

Ask.

● Involve users in the discussion from the start

● Alpha/Beta test to source feedback

● LISTEN

8) Your API Doesn’t Use Best Practices

It’s Not Always 200 OK...

● Using the wrong status codes

● Bad error messages

● Not adhering to standards

ERROR: 418 - I'm a teapot● Use status codes that explain errors

○ 404 Not Found○ 401 Unauthorized○ 500 We Broke Stuff Try Later

● “Bad Request” => “Bad Request: $field is required”● /shutdown isn’t RESTful, it’s RPCful

○ Sometimes this is necessary○ Be honest about it

9) You Don’t Care About Security

NO SSL???

ROLL YOUR OWN AUTH/CRYPTO?!

Security? Who Even Needs That?

More Seriously...

Use SSL

Stop rolling your own crypto

Hire consultants if needed

10) Your API Isn’t Maintained

REST in Peace, API

● No bug fixes

● No new endpoints as product

changes

● No documentation updates

Don’t leave me hangin’

● Plan to maintain your API

○ Docs

○ Support

○ Bug fixes

Thank You!Amanda Folson - Developer Advocate at GitLab

amanda@gitlab.com@AmbassadorAwsum