APIs Need UX Too

We've all been there: Attempting to work with a textual interface to a product or service and the responses come back with no clear error, or what we might change to get a better response. The built-in help is non-existent. We end up banging our head against the keyboard and getting fed up. It doesn't have to be this way. UX is not only “the pretty” or how something looks, but it is in fact about how things work. We'll look at some good and bad API interfaces (and command line tools) and talk about the best practices we can implement in our own products to help our end users have a better experience.

Transcript

1. John Athayde www.meticulous.com APIs Need UX Too RVAJS 17 NOV 2022 @johnathayde @johnathayde@mastadon.social
2. API?
5. Application Programming Interface
6. { "status": "OK" }
9. UX
10. LEVEL OF SATISFACTION THEY ATTAIN FROM USING IT THE PROMPTNESS WITH WHICH USERS LEARN TO USE SOMETHING THE EFFICIENCY THEY ATTAIN WHILE MAKING USE OF IT REMEMBERHOW TO USE IT HOW EASY IT IS FOR THEM TO ERROR-PRONEIT IS HOW
12. User Journeys: There’s So Much More than [product]
15. User Experience Optimize user fl ows through the app • Don’t interrupt the user’s fl ow • User should know where they are at all times • Reduce clicks to achieve a desired result • Reduce friction in the experience
16. DEVELOPER EXPERIENCE DX
17. User Experience Optimize user fl ows through the app • Don’t interrupt the user’s developer’s fl ow • User Developer should know where they are at all times • Reduce clicks calls to achieve a desired result • Reduce friction in the experience
18. LET’S USE AN API!
19. HTTP Response Code 200
20. HTTP Response Code 200 Message: File Not Found
21. HTTP Response Code 200 Message: Syntax Error
23. Confusion & Delay
24. “Really Bad Portal” courtesy of Adam DuVander h tt ps://everydeveloper.com/developer-portal-audience/
25. Libraries/SDKs for Popular Languages
26. Developer Self Service
27. Clear Pricing Up Front
28. Clear Pricing Up Front
29. “Nothing changes user behavior more than a pricing model.” — Gi ff Constable
30. Provide a Free Trial
31. Provide a Free Trial
32. What’s the Status?
33. AUTH
34. Authorize Me! API Keys OAuth Tokens JWT Tokens
35. Authorize Me! API Keys OAuth Tokens JWT Tokens Great for ge tt ing started fast Good for accessing user data Good for limiting database lookups
36. Authorize Me! API Keys OAuth Tokens JWT Tokens Great for ge tt ing started fast Good for accessing user data Good for limiting database lookups Use if you’re only building for developers Use if you want easy access without digging through documentation Use in concert with OAuth to reduce database lookups
37. h tt ps://zapier.com/engineering/static-webhooks/
38. (A Sendgrid Story) Be conscious of early decisions
39. “OAuth Butt” “Many organizations unveiled their API but discover a certain dilemma that makes them believe that they need to operate outside of OAuth 2.0's standard to accomplish their goals. If you fi nd yourself describing your API and saying something like "We use OAuth 2.0, but with API keys," then you might be an OAuth Bu tt . […] It makes it harder to integrate with your API and as a result could hinder widespread adoption.” — James Carr, Zapier h tt ps://zapier.com/engineering/oauth-bu tt /
40. DOCUMENTATION
41. Credit to u/Deep-Ad591
45. Getting Started Guides
46. IA INFORMATION ARCHITECTURE
47. — usability.gov h tt ps://www.usability.gov/what-and-why/information-architecture.html “Information architecture (IA) focuses on organizing, structuring, and labeling content in an effective and sustainable way. The goal is to help users find information and complete tasks. To do this, you need to understand how the pieces fit together to create the larger picture, how items relate to each other within the system.”
48. Good Documentation Makes the World Go Round • Ge tt ing Started Guide, ideally in each language for which you have an SDK • A clear place to ask questions • ACCURATE up-to-date reference • Sample applications • Bonus: ongoing blog posts
49. ALL THE LITTLE THINGS
51. Working Copy/Paste Examples
53. Version the API
54. Don’t kill features/versions without understanding the implications
55. Docs with a Playground
56. CHECKLIST
57. #1 Version Your API
58. #2 Research Your User Flows & Optimize Them for Good DX
59. #3 Write the Documentation You Wish You Had
60. #4 Respond Accurately & Gracefully To Errors
61. #5 Continuous Discovery with Real Users Over Time
62. FINALLY: “It Depends”
63. LEVEL OF SATISFACTION THEY ATTAIN FROM USING IT THE PROMPTNESS WITH WHICH USERS LEARN TO USE SOMETHING THE EFFICIENCY THEY ATTAIN WHILE MAKING USE OF IT REMEMBERHOW TO USE IT HOW EASY IT IS FOR THEM TO ERROR-PRONEIT IS HOW
64. RESOURCES
65. h tt ps://www.apisyouwonthate.com h tt ps://www.everydeveloper.com
66. DEVELOPERUX
67. John Athayde www.meticulous.com www.johnathayde.com www.developerux.com Thank you! @johnathayde (twi tt er) @johnathayde@mastadon.social john@athayde.com