APIs are for computer communication, but people have to implement to them. Why it's so important to do user-centered design for Web APIs, how, and some usability dos and don'ts.

1. APIs are for people too
User-centered design for FASTER APIs

2. What makes a “Good” API
• REST
• GraphQL
• OpenAPI
• Automatically fully documented!

3. Good for whom?
Until you’ve identified who is going to use your API,
how can you make it good for them?

4. Example:
Ticket API
Leadership: We have a
valuable database of events
and tickets!
Engineers: OK!
Leadership: We need a
customer API!
Engineers: OK!
Leadership: Go build one!
Engineers: Yay! I get to use
[ that tech I think is cool ]!

5. Option 1: Tech-centered design
• List the DB objects that will be part of the API
• Decide what URL to use for each object
• Expose queries, GET requests and POST for
changes for each object
• Run documentation wizard
• Hand off to operations team to actually launch,
throttle, support, etc.

6. Option 2: User-centered design
Who What for? What to build?
Music
artists,
labels
List performances
with links to tickets
to increase fan
access/attendance
1. Query: events by artist
sorted by date
2: List: tickets by event ID
price
links to Web site to buy

7. Which is better, faster, scales?
Tech-centered design
• 8 different models exposed
• Event, Venue, Ticket, Category,
Performer, Venue Section, Seat
Traits, Seat grouping
• Query, GET and POST
• Permissions
• API Keys, Throttles
User-centered design
• 2 endpoints
• Highly cacheable on server or
proxy
• No POST
• No API key needed

8. What is a better investment?
Tech-centered design
• No product/design time wasted!
• Developer “saved” 10 hours out of
80 with API generation tools
• Possible outcome: nobody uses,
can’t understand
• Support cost: 10 hours/month for
users who give up in frustration
User-centered design
• 3 weeks lead time built into
project for design and discussion
• 40 hours development time
• Customers adopt API self-serve
• Adoption rate 3/month initially
• Support cost 10 hours/month on
real issues, real users

9. What’s wrong with learning the hard way?
• Your company never finds the time to replace the API.
• It’s very hard to understand what’s wrong with a working API.
• You, or somebody less lucky than you, has to maintain.
• How many engineers bounced hard off the API docs?
• How many engineers were made to figure it out anyway?
• You can never publicly admit you built this.

10. Working
from Use
Cases
When the customer is not your
own front-end team
When you’re not a giant with
100s of use cases ready to go
live

11. 0. Get Product and Design involved
• Will they help?
• May be intimidated at the idea of designing an API
• May not understand why they should get involved
• May have bought into exposing the whole DB
• May believe that the API used by your front-end is enough
• Show them this presentation; ask for user stories

12. 1. Define the User
• Who do you believe is going to use your API?
• What is their need? (Don’t confuse with your need)
• What resources do they have?
• Individual consumer, hobby users, developers
• B2B partners
Iterate! Share internally! Do some customer discovery!

13. 2. Define the User Stories
• As a customer of HRIS™, I would like to integrate other HR
software with my database of employees so I don’t enter
information in multiple places
• As a provider of HR software, I would like to integrate with
HRIS™ software so I can sell my software to HRIS™
customers as easy-to-use and reduce onboard costs
Sometimes user stories expose different kinds of users

14. 3. Go from use cases to endpoints
Use case: Benefits Chat Bot needs employee info to guide
employees benefit choices
Your DB:
• employee
• employee_health_plan_select_event
• employee_commuter_choices
Design:
• Employee directory
• Employee detail joins in other tables
• Location fields, benefits section with health, commuter sections
• company
• company_health_plan_settings
• company_pretax_options

15. 4. Generalize later
1. Benefits chat bot needs to
search for employee and get
what state they live in, and
employment status
2. Survey app needs list of
employees and get name,
email and employment status
What listings, queries or
fields would support
multiple use cases?
Don’t forget to solve at
least SOME use cases ALL
the way through

16. Technical
Details
While implementing, some
choices are win-win
Choose approaches that let
customers get more done in
fewer queries
Result: less ops, performance
and throttling work required

17. "eventId": 103619888,
"category": 32,
"externalListingId": 159632,
"products": [ {
"externalId": "12",
"row": "JD",
"seat": "1",
"productType": "TICKET",
"ga": false },
{ "externalId": "13",
"row": "JD",
"seat": "2",
"productType": "TICKET",
"ga": false },
{ "externalId": "14",
"row": "JD",
"seat": "3",
"productType": "TICKET",
"ga": false } ]
• How you represent
models internally is
not how outside users
think about the world
• Category IDs that
have to be looked
up in a category
request can DIAF
Don’t expose DB models
as URLs

18. Combine information into one result
Use Case: Culture Survey app needs to get employee status,
email address, start date to send appropriate survey
Your DB:
• employee table: email, start date
• status_event table: event date and codes 1 ... 8
• Codes mean “Full-Time”, “Contractor”, “Terminated”, etc.
Design: Join employee’s latest status, convert to human-
readable string, and include in employee directory listing

19. Most auto-generated API docs:
• Focus on format and data types
• Rarely covers meaning
• Almost never explains what you can do
• Repetitive
• Uselessly Repetitive
• See also: Repetitive definitions of repeated things
• Can DIAF

21. "salary": {
"amount_raw": "4791.67",
"currency_type": "USD",
"date": "2019-09-13",
"guid": "56ce9ef4-e44b-483a-b356-
81cc114bbe71",
"is_hourly": false,
"payroll_job_id": "a8efeda8-1b17-414a-a53f-
76280a601feb",
"rate": "semimonthly",
"yearly_amount": 115000.08
},
OMG what does it mean

22. Design read and write independently
GET employee/[id]/employee.json
…
"salary": {
"amount_raw": "4791.67",
"currency_type": "USD",
"date": "2019-09-13",
"guid": "56ce9ef4-e44b-483a-…",
"is_hourly": false,
"payroll_job_id": "a8efeda8-1b17-414a-…",
"rate": "semimonthly",
"yearly_amount": 115000.08
},
POST employee/[id]/salary_change
"salary": {
"amount_raw": ”5051.00",
"currency_type": "USD",
“is_hourly": false,
"rate": "semimonthly",
}
GUIDs, dates are generated
Yearly amount is calculated
Don’t worry – it can still be REST

23. Versioning: The Cost
1. Cost to YOU (Your company)
• Write a new API
• Test and fix a new API
• Performance tune a new API
• Notify customers/users
• Support old and new APIs for months to years
• Deprecate old API finally and still deal with complaints
2. Cost to EVERY USER of the API
• Find time to rewrite something that was working perfectly
• Rewrite a bunch of code, test, fix bugs

24. Versioning: Don’t. Really
Design your API not to need versioning
• Don’t tie to internal data models in the first place
interfaces should decouple
• Start small: Minimum Viable API
• Good APIs are extensible
• E.g. use response envelopes – easier to extend
• Add fields, endpoints, queries as needed
• Base on use cases -- especially real-world proven use cases

25. Handling change without versioning
If you must re-organize: create replacement endpoints
/api/events/X/event.json
/api/events/X/event_faster.json
If you must remove endpoints:
• Replace as above - one by one only as needed
• Deprecate the one that will be removed
• Throttle the bad one if necessary
https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown.html

26. Recap
Work from use cases
80/20 Rule: 80% of an API’s value
comes from 20% of your data
Overbroad APIs are expensive to
support and provide much lower
return on investment
Don’t expose your DB as your
public API!

27. Thank You
I enjoyed working on this rant
Who am I
• Lisa Dusseault
• CTO, Founder @Compa_as
• Podcast: Engsplaining
• Twitter: @milele