That Conference 2018 – Launching with Now, Next, and React

That Conference 2018, Kalahari Resort, Lake Delton, WI
Launching with Now, Next, and React

Day 2, 7 Aug 2018  10:30 AM

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.

Executive Summary

  • Summary of tech stack used at Northwest Mutual and on Nicholas’ personal project
  • Recommend combination of micro services and micro apps
  • Koa vs. Express
  • Use Next?


Micro-Service vs. Micro-App



  • Encapsulate business logic
  • Encapsulate persistent data
  • Reusable, stand-alone solution
  • Not always a 1:1 relationship between micro-apps and micro-services
  • Independent
  • Tidy, clean



  • Client facing code
  • May call mlutiple micro-services for data or computations
  • Handle interactions and specific complex problems
  • Aggregates inof from multiple services


The Tech Stack

  • Node
    • Released support for async/await
  • Koa – “fix” Node; minimal lib as extraction of HTTP module of Node
    • Solves same problem as Express
    • Promises, async/await
    • Now at Koa 2–far less confusing than Koa 1
    • Choice for micro-service
    • Avoids “callback hell”
    • Choice: Express vs Koa
  • Express – augmentation for node that allows setting up simple server
    • Can end up “callback hell”–messy callback architecture
  • PostgreSQL
  • React
  • Next – like React, but SSR a bit differently than React does SSR
    • Also bundled with some “auto magical” elements
    • Good for supporting SEO
  • Redux – state management tool
    • Source of truth that feeds application



  • React 16 solved a lot of problems
  • React portal
    • Render a component and drop it somewhere else in your application
    • Specify what to render, where to render it
  • Fragment
    • Can return multiple components (e.g. HTML elements)
    • <React.Fragment>
    • Could return several table columns, not wrapped in <div>
  • Context API
    • Have state that’s inherited down with component hierarchy
    • Avoid passing things down the tree



  • Recent update that took advantage of all of React 16
  • Does things “auto-magically”, secretively, just works out-of-the-box
  • You call next command; it fires up server, automatically does various things
  • No longer have to explicitly import React into any of your components


Decisions – Handling Server Requests

  • For API used Kora – conceived for and caters to async/await funcs
  • For apps, used Express
  • Subtle differences between the two
    • Express is lower barrier to entry
    • Tons of tutorials out there
  • Most differences deal with middleware
  • For middleware-heavy apps, Koa better


Decisions – Rendering

  • Client-side vs. server-side
  • If SEO is concern, server-side might be simpler to roll out
  • Server-side rendering opens the door to some PWA setups (Progressive Web App)
  • Client-side rendering makes SEO harder
  • For server-side: React vs Next?
  • Anxiously awaiting React’s async rendering
  • Went with Next


Decisions – State Management

  • There are many options, and tons of patterns
  • Redux vs MobX vs others
    • MobX worth a look if you’re starting from scratch
  • Meiosis Pattern
  • Context API  (in React)


ThinkMinded Architecture

  • Micro Service (just 1)
    • Node, Express
  • Micro App
    • React, Next, Node, Express
  • Has mindset of allowing others to consume our data
    • So micro service is a standalone API


Micro App Architecture (ThinkMinded)

  • Redux
  • Redux store has sequence
    • Action => Dispatcher
    • Reducer
    • State
    • => Back to GUI


Engineering – React

Engineering – React / Redux

Engineering – Next / Redux

  • Similar to above, but don’t import React
  • Biggest difference, package.json changes, use next commands to do everything
  • Next uses Webpack
  • Next automatically creates API, based on file system
  • Hot module re-loading
  • Automatically indexes


Deploying with Now

  • Now is a platform for global deployment
  • Generates a URL upon deployment (staging)
  • (vs Gitlab)
    • Gitlab for bigger teams
    • Now has nice CLI
  • Staging can then be aliased to production
  • Works to deploy Node.js apps and docker powered apps
  • Preferred for short/small personal projects


That Conference 2018 – Correcting Common Mistakes When Using async/await in .NET

That Conference 2018, Kalahari Resort, Lake Delton, WI
Correcting Common Mistakes When Using async/await in .NET – Brandon Minnick

Day 1, 6 Aug 2018  4:00 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.

Brandon Minnick

Developer Advocate, Microsoft


Executive Summary

  • Helps to know underlying IL that’s generated
  • Helps to know core task-based objects that async/await use
  • ConfigureAwait(false) if you don’t need to come back to UI thread
  • .GetAwaiter().GetResult() instead of await to get synchronous execution

Multi Threading

  • e.g. ReadDataFromUrl
    • Our method is async
    • does await on DownloadDataTaskAsync
    • 1st chunk of code is run by the thread that calls this method
    • 2nd thread–calls the Download method
    • After await, execution picks up with 1st thread
  • Typically, first thread, i.e. main thread, is the UI thread
  • UI thread
    • Draws UI on screen
    • Rule-of-thumb for executing on UI thread. Because refresh rate is 60Hz, don’t take more then 1/60 sec (17 ms)

Intermediate Language

  • Compiler generates class for your original method
  • Implements IAsyncStateMachine
  • Every local variable from method becomes private field in class
  • MoveNext method
    • Giant switch statement
    • $PC keeping track of state
    • Also a big try/catch block surrounding everything

Quick Review

  • async keyword adds 100 bytes
  • Every async method becomes a class

Await Every Async Method

  • Non-awaited async methods hide exceptions
  • Ditto for Task.Run — GetAwaiter().GetResult() will ensure we catch exception

Let’s Fix Some Code

  • Can’t await in a constructor
    • ICommand–made for fire and foreget
    • In Execute method, do async lambda with await
    • So from constructor, we can call MyCommand.Execute(null)
  • Never use async void ?
    • Not entirely true
    • Don’t use async void when not on UI thread
    • But on UI thread, if you throw exception from within async void–you’ll catch the exception
  • So from constructor, call Initialize(), which is an async void and can do the await
  • NEVER use .Wait
    • Blocks calling thread entirely
    • Doesn’t unwrap an exception
  • NEVER use .Result
  • Way better method
    • GetAwaiter().GetResult()
    • Does unwrap any exceptions
    • Can get the result from the async method
  • Note: .GetAwaiter().GetResult() is to be used in non-async method
    • In async method, just use await keyword
  • ConfigureAwait(false)
    • By default, you context switch back to UI thread
    • But this is expensive–background thread has to wait for UI thread
    • Context switch takes time
    • When background thread is done, execution stays on that background thread. Does not come back to UI thread
    • But note that you do need to come basck to UI thread if that method does some stuff with the UI, e.g. modify a control
  • ConfigureAwait(true)
    • This is the default, equivalent to not having ConfigureAwait() there at all
  • Don’t call .Result
    • Replace with await that method call to get the result directly
  • Special case, returning await something that returns Task<>
    • You can return the task directly, rather than awaiting it, then doing async on the method
    • Look for “return await”
  • Exception to this rule
    • You should await if you want to catch exception in method that you’re calling
    • So you could argue not to every do that trick

Async/Await Best Practices

  • Never use .Wait or .Result
    • Use await keyword
    • Or .GetAwaiter().GetResult()
  • Fire and forget tasks
    • Use ICommand
    • (or) async void (if you know you’re going to be on main thread)
  • Avoid return await
    • Remove async keyword
    • Except in try/catch blocks or using blocks
  • Utilize ConfigureAwait(false) as much as possible
    • In methods that don’t touch the UI

Xamarin University

  • Various course, e.g. CSC350: Using async await

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


  • 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


  • 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
    • 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 2018 – Know What Your Code Is Doing to SQL Server

hat Conference 2018, Kalahari Resort, Lake Delton, WI
Know What Your Code Is Doing to SQL Server – Kevin Boles

Day 1, 6 Aug 2018

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.

Kevin Boles

Executive Summary

  • Handful of specific examples of ways that you can end up with poorly performing SQL Server queries
  • Improper use of Entity Framework sometimes to blame
  • Always pay attention to exact T-SQL that is being used



  • Recommend 192GB on server, go beyond max memory (128GB)
  • In memory OLTP now down in standard edition
  • SQL Server 2016–It Just Runs Faster
    • Good blog posts on performance improvements
  • Get on 2016 or 2017


Entity Framework is tool that simplifies, but lower performance

  • Can be very productive
  • Several traps, easy to fall into
  • Other ORMs have similar problem


Being too greedy with rows

  • EF exposes objects without knowing values
  • E.g. pull data out to list, when do Where clause on the list
    • Pulls entire table before filtering
  • Do filtering on SQL Server
    • Provided that you ave the proper filter
  • Or could bring back to IQueryable


N+1 Select Problem–minimize trips to DB

  • ANTS performance profiler
  • E.g. One query to parent entities, 2nd query for each child to get related entities
  • Round-trip for each child query
  • Lazy Loading
  • “N+1 select problem”
  • If you know you want child data ahead of time, do the original query to include it
  • Use Eager Loading
    • .Where, .Include
  • Make sure that you really need them
  • Don’t do aggregation in client–do it in SQL Server
  • E.g. if we’re just counting child objects, do it with aggregate function in SQL Server
  • Don’t iterate and don’t get data that you don’t need


Being too Greedy with Columns

  • E.g. pull all Pupils from school, then iterate to dump out certain stuff
  • Selecting all columns when you just need subset of columns
  • EF doesn’t know what columns you want
  • Causes two problems
    • More data than we need
    • Impossible to index, since we pull everything back
    • If acceptable, can be faster because you don’t wait for confurrent transactions
  • If you’re pulling all columns, you’re locking entire table for the length of that query
  • Select new to just get you want


Mismatched Data Types

  • If data types don’t match, even simple queries can perform poorly
  • E.g. search for entities with particular zip code
  • Dev system should match prodution system in terms of scale
  • Find query runs fast, EF runs very slowly
  • Query plan warning
    • Function on a column in a WHERE clause
  • Column in database is VARCHART, but .NET has string, which is UTF16 Unicode
  • SQL Server does
    • INDEX SCAN of every zip code
    • Big I/O cost
    • Then converts the data–CPU hit
    • Optimizer can’t do prediction because  data is different than what’s in the index
  • Solution
    • Edit model to tell EF to use VARCHAR, using column annotation
    • In code, attribute
  • Do not let EF create models, code-first



  • He recommends not using one



  • 3 things to remember about stuff on internet about SQL Server
    • Who wrote it
    • When was it written
    • Does it apply to my system
  • ADO.NET Parameterized Queries
  • AddWithValue–get rid of this


Overly Generic Queries

  • Allowing searching on multiple fields
  • So we construct one query, where clauses for each search field
  • == null or matches
  • IS NULL OR stuff gets into query
  • Bad because it builds query plan just once for all the possible search combinations
  • Always runs same query plan, no matter what you search on
  • Can’t do a seek on index
  • Options
    • Stored procedure — Gail – “catch all queries”
    • Conditionals in EF side, exclude clauses
    • Make SQL Server recompile plans each time–from within EF. Sometimes good
    • Could write interceptor, option(recomiple)


Bloating the plan cache

  • Reuse of execution plans often a good thing, avoid regenerating plan
  • In order for a plan to be reused, the statement text must be textually identical, wihch as we just saw, is case for parameterized queries
    • Ad-hoc workloads


Skip / Take

  • Next time we run query, we get different query plan
  • Enable SQL Server setting ‘optimize for ad-hoc workloads ‘
    • Less aggressive at caching plans, generally a good thing
  • EF6, pass in lambdas
    • In SQL, values are paremetrized, so we don’t recreate cache plan


Inserting data

  • EF will run separate INSERT statements for every row being added
  • Not good if you have to insert a lot of data
  • Can use EF.BulkInsert or use EF 7 (has this out-of-the-box)


Code First, Performance Last

  • Never allow your code to create your storage constructs
  • (He means–code-first used to refresh database object)


Other Potential Issues

  • Improper use of IN clauses
    • >16 clauses in IN clause if bad
  • Correlated subqueries instead of JOINs
  • Parameterized queries with parameters defined to be length of data they contain
  • Chatty apps
  • Security conerns
  • Increased IO and app bloat due to asking for too mcuh data


That Conference 2018 – Finding Your Way to a Microservices Architecture

That Conference 2018, Kalahari Resort, Lake Delton, WI
Finding Your Way to a Microservices Architecture – Dana Hart

Day 1, 6 Aug 2018

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.

Dana Hart
Northwestern Mutual

Executive Summary

  • Lots of good reasons for re-factoring monolithic application as microservices
  • Architecture has multiple micro SPAs talking to multiple microservices


Monolithic application

  • Browser
    • UI / Business Loic / User Logic
    • Databases
  • One application on single platform
  • Drawbacks
    • Maintenance
    • Hard to test
    • Longer deploys
    • Longer downtimes
    • Doesn’t scale
  • How we got there
    • Probably started out small
    • Features have been added


Scaling the mono

  • Development–multiple teams in one repo
  • Continuous Deployment – updates = outages, higher risk
  • Increased Transactions – ru nmore copies of application?  Scale out metal?
  • Is this good enough? Working?


Frustration is an important part of success


Software microarchitecture

  • Set of patterns used together to realize parts of a system
  • Building block for piecing together cohesive portions of an overall architecture



  • Structure application as collection of loosely coupled services
  • Enables continuos delivery and deployment of large, complex applications



  • UI talks to various microservices
  • Each microservice talking to one database


Reasons to convert

  • Decomposes complexity
  • Developed independently
  • Deployed independently
  • Scaled independently
  • Smaller deploys
  • More frequent deploys
  • Lower deployment risk


How to start

  • Find piece that can exist independently
  • Don’t just convert, but re-factor


REST review–constraints

  • Uniform interface
  • Client-server
  • Stateless
  • Cacheable
  • Layered system
  • Code on Demand


Define your subdomain


REST review

  • Sensible resource names
  • XML and JSON
    • Recommend JSON over XML
    • Easier to consume by browser
  • Fine-grained resources
    • Simple resources that you can apply CRUD to
  • Idempotence
    • Get same response every time if inputs are the same
  • Safety


Micro SPAs

  • Take original monolithic UI
  • Split into separate pages, each being a SPA
    • /store
    • product
    • /order


Deployment Patterns

  • Multi service instances per host
  • Service instance per Host / VM / Container
  • Serverless deployment
  • Service deployment platform
    • Automated infrastructure


Move everything to cloud


Reverse proxy

  • URL goes thru reverse proxy (external request)
  • Look up services, find target address
  • E.g. use NGINX


API Gateway

  • SPA Containers send requests
  • To API Gateway
    • Could implement security
    • Load balancing
  • Farms out to API Containers


Micro Application platform–diagram

  • Request
  • Reverse Proxy
  • SPAs
    • Can talk to one or more services
  • API Gateway
  • Services
  • Databases


At end

  • Multiple SPAs
  • Multiple services
  • No deployment downtime
    • Pre-production environment
    • Kubernetes handles this




Q: When do you decide to create an API that might combine logic from two sub-domains?

A: We wouldn’t combine the services, but let the UI do the model translation between the two services. But sure, you could add a service that aggregates data from multiple services.


Q: How do you handle versioning?

A: Many opinions around versioning. We have pattern of “v1”, “v2” in front of API. “No breaking changes” unless it’s a major version chance.


Q: How do you decide what goes in what database?

A: We still have one large database. If the entities have relationships, we’d be hesitant to split them out.


Q: How do you manage to get common look/feel across the SPAs

A: It’s not easy. We had designers to create common UI Sketch components. Then devs create UI framework around these common elements. Partnership between Engineering and Design.


Q: How did you avoid applying legacy change management techniques (monolithic) to new architecture. Had to educate various teams to demonstrate that we’re now running with lower risk. Dev team “owns” the result of a deployment, responsible for it. We use New Relic for monitoring.


Q: We have 3rd party integration with a service that is not stateless.

A: Sometimes you do get stuck with a vendor’s implementation. Could give examples to vendor of what work better for you.


Q: Where do you pull stuff from multiple services together?

A: We do it in UI layer, model translation, pulling stuff together.

That Conference 2017 – From Dull to Dazzling: How Visualization Enhances Data Comprehension

That Conference 2017, Kalahari Resort, Lake Delton, WI
From Dull to Dazzling: How Visualization Enhances Data Comprehension – Walt Ritscher

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.

Walt Ritscher

  • LinkedIn Learning – online video training (formerly
  • Content available on both sites
  • 7100 courses
  • @WaltRitscher

Executive Summary

  • Showing data visually can make patterns and trends suddenly very obvious
  • Varying graphical data items’ size, color, position, contrast or shape can make a big difference in how a user views the data
  • Review of various data visualization tools and some examples of graphs

Your Data

  • We all have various data sources and lots of data
  • Big Data – lots of data
    • Gathering at unprecedented rate
    • Many sources–sensors, online transactions, medical, tweet streams
  • If you don’t use/analyze data, you’re a hoarder
    • Stored data is inert
    • Need to make it Actionable
  • Raw data can be hard to understand
    • E.g. Big spreadsheet
    • “Wall of text”


  • Bring human optical system into picture
  • Visual recognition is 60,000x faster than text recognition

Example – Anscombe’s Data

  • 4 sets of XY data, with averages and std deviation
  • Visually view same data
  • We see patterns
  • And pattern anomalies

Demo – Differences – Test

  • Changes to hue, saturation, size of object
  • Change shape–quickly recognize
  • Can’t find difference if original shapes very different


  • Size
  • Color
  • Position
  • Contrast
  • Shape

Highlight Differences with 5D

  • Use one of the differentiators to highlight a difference
  • If original set is uniform in shape, but different colors, you’d differentiate by shape to make it stand out
  • Counting # instances of “8” shape
  • Could colorize rectangles around digits
    • Heat map
    • Easy to spot area with higher numbers
  • Or could change size of shape by value
    • Bubble chart
    • Easy to see high growth
    • But harder to see actual numeric data

A Word about Colors

  • Chart–happy customers green, angry red
  • Don’t use green/red
  • Problem–green/red color-blindness about 10% can’t differentiate
  • Could do Blue / Red–easier to differentiate (99.5% population)
  • Example–colorizing heatmap
    • Which colors seem to be “higher” value color
    • Brain doesn’t do this
  • Rule: don’t differentiate by Hue
    • Differentiate by Saturation or Lightness

Motion and Animation

  • Demo – slightly changing something, moving something slightly on screen
  • Your brain sees the motion
    • Can see something moving even 1-2 pixels
  • Can animate data, showing stuff in sequence
  • If you have time-stamped data, consider animating that

Warning–eyes can be deceived

  • With a lot of lines, you can’t see more than a couple black dots
  • Pie chart – 30% slice looks smaller if it’s in the back
    • Never use 3D pie chart
  • Displaying change in one variable using area or volume
    • Showing relative sizes using area–doesn’t work

Terminology – The Buzzwords

  • Categories of visualization
    • Data Visualization – show data via graphical
    • Infographic – design friendly approach to visualization
    • Motion Graphics or Animated – use motion to accentuate

Data Viz Categories

  • Business tools – Excel
    • Excel continues analysis engine
    • Can launch in background and generate results or chart
    • Could take screenshot in the background
  • Drawing tools – Illustrator
  • Code tools – Visual Studio

Data Viz Tools

  • Processing – programming language
  • ProcessingJS
  • Tableau
  • D3.js
  • R – language to manipulate data (no viz)

Data Viz Browser Tools

  • SVG
  • 2D Canvas
  • WebGL


  • Sideways bar chart
  • Excellent
  • Web site allowing you to pull data out ( ?


  • Glasswire – exploring data
    • Timeline with sliders
    • Nice alternative to having two calendar dropdowns


  • Designer-friendly approach to data visualization
  • View uploads by category
    • Wedges in triangle
    • “Umbrella graph” ?
    • Callout coming out of wedge

Motion Graphics

  • NASA Perpetual Ocean
    • Latitude, Longitude
    • Flow direction & speed
    • Timestamp


  • Visualization Data
  • Tufte


  • Time-tested concept but still useful
  • Have done bar and line charts forever
  • But lots of new charts out there
  • New charts
    • Waffle chart–boxes
    • Hierarchical Edge Bundling–connecting nodes, bezier curves, trends pop out
    • Adjaceny matrix–e.g. Les Miserables Co-occurrence; awesome animation
  • D3.js
  • Bret Victor

That Conference 2017 – 12 Reasons Your API Sucks

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


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

Executive Summary

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


  • 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–
    • 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


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


  • 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