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