Embed Size (px)
Citation preview
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
