That Conference 2017, Kalahari Resort, Lake Delton, WI
12 Reasons Your API Sucks – D. Keith Casey Jr

Day 3, 9 Aug 2017

Disclaimer: This post contains my own thoughts and notes based on attending That Conference 2017 presentations. Some content maps directly to what was originally presented. Other content is paraphrased or represents my own thoughts and opinions and should not be construed as reflecting the opinion of the speakers.

D. Keith Casey Jr

keith@caseysoftware.com

@CaseySoftware

• Twilio, Okta, Clarify
• A Practical Approach to API Design – theapidesignbook.com

Executive Summary

• There are a number of things that you can do to deliver high quality API cod

Assumptions

• APIs are important part of your job
• Use them on a regular basis
• Potentially build them too
• Sometimes public, sometimes private
  • Same principles should apply
  • For internal API, if it’s awful, internal users can’t use another one
  • I.e. Adoption = in spite of your best efforts
• Nothing is perfect
  • You make mistakes
  • Your providers make mistakes
  • That other team are knuckleheads
    • “Why do they work here”?

Developer Experience

• “Developers are users too”
• Don’t Make Me Think – Krug
  • When you make something figure something out, you’re taking time away from their main objectives
  • When you interrupt someone, you “reset” their work
• Developers
  • Want to build something useful
  • Want to go home at end of day
• Set aside an hour – you really tried
  • Phone calls, e-mails, IM, Slack, etc.
  • “Do you have a minute”?
  • TPS reports
• At Twilio
  • 5-min onboarding experience

1 – Documentation

• If delivering documentation via PDF–stop
• HTML–github.com/lord/slate
  • Slate great, widespread use
  • You write in markdown
• When people are ready to use the API, documentation needs to be ready
• Let’s get interactive
  • Swagger – now Open API
    • Load up in browser and interact with endpoints via browser
    • Level of skill required to try out goes way down
  • (competitors) JSON Schema, API Blueprint

2 – Incomplete Docs

• If you’re only documenting SDK, that’s not complete API documentation
• Must have actual API reference docs
  • Exact syntax for each endpoint
  • High level of detail
• JavaScript drinking game–random noun + .js
• When you take dependency on 3rd party library
  • If it’s not popular, you’ll end up bringing it in house
• Need reference docs + How To docs
  • Basic API is straightforward to figure out
  • But need to tell developers how to do something useful

3 – Getting Started Code

• Sample code that solves a problem
  • How to do a “thing”
  • But nobody cares about that thing
• 1st thing you need
  • Authentication
• Need to give them sample code that solves an important problem
  • But we don’t know what’s important
  • Customer wants you to solve their specific problem
  • User judges docs based on whether it solves their problem
• Work quickly to make someone successful

4 – “Innovative” Interfaces

• Nobody really wants innovative
• Everyone tries to create their own
  • HTTP verbs – important that they’re standard
  • Response codes – don’t do this
  • Your own protocols – also huge ecosystem out there
    • Probably not qualified to build your own
  • “Don’t Be Dumb”

5 – Authentication

• Don’t roll your own “encryption” scheme
• Don’t roll your own “new” methods
  • You’re not qualified to create something new
  • Good encryption scheme have been out there a long time and have been hammered on
  • You’re new scheme won’t have been deeply reviewed and tested
• Use existing scheme like Oauth
  • Less training required – for users
  • Reuse common libraries for clients & server
  • Faster on boarding – for internal developers

6 – Inconsistencies

• Consistency of URIs
  • See some URIs, you want to extrapolate to figure out other URIs
• POST -d {data}
  • Use 201 Created and Location header
  • Don’t do 201 for most, then 200 for one
• If you are inconsistent/wrong on day 1, you’ll have to support that mistake for years

7 – Poor Modeling

• Example–coffee cup w/handle
  • Accomplishes primary goal (don’t get burned)
• When building API, what is user’s primary goal
  • Single sentence, primary use case
• Affordances
  • What problems/tasks does it make simple?
  • What is the API producer’s goal?
  • What do you want to do?
  • (or) Why are people giving us money?

8 – Stack Overflow Problem

• Many different way to do something
  • Other places are replicating your documentation, advising how to do something
  • And these documents end up on Google
• E.g. Multiple ways to pass auth token into API
  • E.g. Auth Header, URL, or body
• Just give them one way to do something

9 – Your Sh.. Stuff Is Broken

• Is Support run by developers?
• What does your uptime look like?
  • Never 100%
  • Cost increases exponentially as you add digits to %
  • Two digits easy
• Do you have a Trust page?
  • Usually yourapi/trust — status of issues, history, what happened
  • Need to be open with the devs who are using your API
• Need to make sure your stuff works
  • SLA in place once people are using it
• Core hours during which API must be up
  • And some users out there who need it during off hours

10 – Error Messages

• Bad error message–unhelpful
• “Don’t do this to people”
• E.g. 404 – “Item Not Found” — not great, just repetitive
• Error code
  • 404, Item not found, E000007
• Add error_code and more_info with URI that explains error code
  • Simple
  • And you better have information on the error at the page
• E.g. HAL – additional links with every payload
  • Typically return this stuff with an actual resource
• Could avoid response body entirely
  • Just set 404
  • And add some stuff to header (spec allows this)

11 – Logging and Debugging

• API going to break, unavoidable
• RunScope – good tool, proxying, catching web hooks
  • Web-based
  • Not appropriate in regulated field
  • Don’t use if you can’t leak private data
• Fiddler
• Postman
• Building Your API Utility Belt
  • Another talk
  • Use the right tool for the job

Building

• “Principle of Least Surprise”
• Designed workflows
• The One True Way
• Authentication

Maintaining

• Error messages & handling
• Logging & debugging

12 – Do you Have a Business Model

• You’re building trust with users
• Fastest way to destroy trust is to disappear as a business
• If your business disappears, you’ve just screwed somebody
• API must support bottom line of API builder
• As customers become more successful, scaling up with your API, you make more money
• If just an experiment, tell people that