That Conference 2018 – API Design Isn’t Just Nouns and Verbs

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

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s