That Conference 2018, Kalahari Resort, Lake Delton, WI
API Design Isn’t Just Nouns and Verbs – Keith Casey

Day 1, 6 Aug 2018  2:30 PM

Disclaimer: This post contains my own thoughts and notes based on attending That Conference 2018 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.

Keith Casey

• Okta – SSI identity management on the web
• OAuth as a service, for Fortune 10 companies
• “A Practical Approach to API Design” – Casey

Assumptions

• Nothing/nobody is perfect
  • Will be attacks against API, some intentional, some not

What Is an API

• contract about how two pieces of software interact
  • Can have lots of ceremony (e.g. SOAP) or less (e.g. REST)
  • REST is not a protocol, but a pattern for interacting with things
• How one piece of software talks to another

Application Programming Interface

• It’s an interface
• We have users of our API
• “Don’t Make Me Think” – Krug
  • Can apply same principles to API, just like GUI
• Stop and think about how API appears to its users

What are we doing now?

• Frameworks for creating RESTful services–there are tons
• We generally default to some framework for building an API
• Typically it just maps tables in database to verbs–CRUD over HTTP
  • But we normally don’t want to expose row-based pattern as the API

What is Bootstrap?

• Clean, simple UI
• Standard, consistent, reusable components
• The bane of every UX designer

Why ?

• Bootstrap treats every application the same
  • Ignores the application, what they use it for, how they use it

GraphQL

• Expose additional data from database via API
• “GraphQL is the CSV of API Design”
  • Ignores requirements, just give them every field and user can choose
• Same thing, treats every application the same

What Should We Do Better?

• E.g. Anonymous visitor to web site, want to create user account
  • ..so that I can see my account balance
• Must ask why on user story in order to understand the requirement
  • Can then build the right thing, better, faster
• The things that we build need to be valuable to users
• Developers want to
  • Build something useful
  • Go home

Think About the Story

• What are the choices available to a user at any given time

Steps in Designing API

• Identify who uses API
• Identify high-level activities
• Break down into steps
• Create API Definitions
  • Prior to this step, it was a business process
• Validate API

Identify Participants

• List consumers of the API (directly or indirectly)
  • e.g. internal or external
• Capture a bit about them–location, description

Identify High-Level Activities

• Activity–work that produces a desired income, accomplished by one or more participants
  • Must understand user’s goals at this point
• Activity might have multiple steps
• Make note of description, participants

Break Down into Steps

• Each step is accomplished by single participant
• Step may have stages executed by different participants, but each step maps to single participant
  • Watch out for “and” steps–could be multiple steps

Create API Definition

• Identify resources (the nouns)
• May start to find dependent/nested resources
  • And business rules around the relationships
• If API user needs to understand database schema in order to use API
  • You’re doing it wrong

Resource Relationship

• e.g. Movie, Actor, Character relationship

Validate Your API

• Ensure that your API will meet the requirements of the users
• Walk through each use case
  • Individual steps in use case on notecards
• You document how many activities need each API action
  • Helpful to know how widely used each endpoint is
  • Correction–each activity has steps, each step on a notecard; document which activities each step needs to be a part of

Validation Options

• Compare API capabilities against UI wireframes
• Build simple mock interfaces in a micro-framework
• Write example code showing how to use it
  • Mock API, Happy JS?
• Write end user documentation

What Should We Avoid?

• Don’t assume we know all the use cases
  • e.g. multi-tool that has everything

Don’t collect or share extra data

• Combridge Analytica
• Why should people share this information?
• How might a bad actor use this information?

Don’t Leak Your Own Data

• E.g. giving user an incremented customer ID
• What can someone tell by using your API?

Don’t Roll Your Own Encryption

• Use an existing library
• No, no, no don’t do your own encryption

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