Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Upcoming SlideShare
What to Upload to SlideShare
Next
Download to read offline and view in fullscreen.

Share

APIs are for People Too

Download to read offline

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.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to like this

APIs are for People Too

  1. 1. APIs are for people too User-centered design for FASTER APIs
  2. 2. What makes a “Good” API • REST • GraphQL • OpenAPI • Automatically fully documented!
  3. 3. Good for whom? Until you’ve identified who is going to use your API, how can you make it good for them?
  4. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
  20. 20. "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
  21. 21. 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
  22. 22. 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
  23. 23. 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
  24. 24. 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
  25. 25. 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!
  26. 26. Thank You I enjoyed working on this rant Who am I • Lisa Dusseault • CTO, Founder @Compa_as • Podcast: Engsplaining • Twitter: @milele

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.

Views

Total views

331

On Slideshare

0

From embeds

0

Number of embeds

12

Actions

Downloads

1

Shares

0

Comments

0

Likes

0

×