API Design isn't Just Nouns & Verbs

Say it with me: An API is not CRUD over HTTP. Too often our tools and frameworks encourage us to wrap a thin routing layer around our database and call it an API. While this is quick and easy, it’s also wrong and more wrong. When we consider our API, let’s shift our thinking from nouns and verbs to use cases and goals.

In this session, we’ll step through a straightforward, repeatable process to design interfaces that speed understanding, increase adoption, and make your API the high point of their day.

Transcript

1. API DESIGN IS NOT JUST NOUNS & VERBS D. Keith Casey Jr keith@caseysoftware.com / keith.casey@okta.com @CaseySoftware
2. WHO AM I?
3. WHO AM I?
4. WHO AM I? http://TheAPIDesignBook.com
5. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
6. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
7. ASSUMPTIONS • APIs are an important part of your job • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private @CaseySoftware
8. ASSUMPTIONS • Nothing is perfect • You make mistakes • Your providers make mistakes • That other team are knuckleheads @CaseySoftware
9. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
10. DEFINITION • … is a set of routines, protocols, and tools for building software and blah blah • … is a contract between two things describing how they interact blah blah • … is how one piece of software talks to another piece of software blah blah Ref: https://infogalactic.com/info/Application_programming_interface @CaseySoftware
11. APPLICATION PROGRAMMING INTERFACE @CaseySoftware
12. APPLICATION PROGRAMMING INTERFACE @CaseySoftware
14. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
15. FRAMEWORKS
16. GET PUT POST DELETE noun1 /noun /noun1/{id} /noun1/{id} /noun1 /noun1/{id} noun2 /noun /noun2/{id} /noun2/{id} /noun2 /noun2/{id} noun3 /noun /noun3/{id} /noun3/{id} /noun1 /noun3/{id} noun4 /noun /noun4/{id} /noun4/{id} /noun1 /noun4/{id} @CaseySoftware
17. HELLO BOOTSTRAP @CaseySoftware
18. WHAT IS BOOTSTRAP? • A clean, simple UI • Standard, consistent reusable components • The bane of every UI/UX designed out there @CaseySoftware
19. WAIT… WHY? Bootstrap ignores the application, who uses it, what they use it for, and how they use it. @CaseySoftware
20. WAIT… WHY? Bootstrap ignores the application, who uses it, what they use it for, and how they use it. @CaseySoftware
21. GRAPHQL!!! @CaseySoftware
22. (Keith, don’t rant here.. take a deep breath.) Forget it. I know you’re going to anyway. @CaseySoftware
23. GRAPHQL IS THE CSV OF API DESIGN (If you tweet that, make sure to tag me @CaseySoftware so I get the hate tweets, not just you. ) @CaseySoftware
24. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
25. As an anonymous visitor to the website, I want to create a user account @CaseySoftware
26. As an anonymous visitor to the website, I want to create a user account so that I can see my account balance. @CaseySoftware
27. THINK ABOUT THE STORY @CaseySoftware
28. DESIGNING YOUR API @CaseySoftware
29. STEP 1: IDENTIFY PARTICIPANTS • List consumers of the API (directly or indirectly) • e.g. internal developers, external developers, system admins, users of the system • Capture a little about them: location, description @CaseySoftware
30. STEP 2: IDENTIFY ACTIVITIES • An activity is work that produces a desired outcome and is accomplished by one or more participants • An activity might have multiple steps – that’s OK • For each activity, you will capture: the name, the participant(s) involved, and a short description @CaseySoftware
31. STEP 3: BREAK ACTIVITIES INTO STEPS • Activities are composed of steps, with each step being accomplished by a single participant • A step may have stages conducted by multiple participants, but a single step should only be executed by a single participant at a time (aka keep splitting up steps) • For each activity step you identify, you will capture: the activity, the step name, the participant(s) involved, and a short description @CaseySoftware
32. STEP 4: CREATE API DEFINITIONS • Identify the resources • You may start to find dependent/nested resources • Understand which resources are dependent on each other and how @CaseySoftware
33. RESOURCE RELATIONSHIPS @CaseySoftware
34. STEP 5: VALIDATE YOUR API • Ensure that your API will meet the requirements of everyone using it • Work through each of your use cases @CaseySoftware
35. VALIDATION OPTIONS Compare API capabilities against UI wireframes Build simple mock interfaces in a micro-framework Write example code showing how to use it Write the end user documentation @CaseySoftware
36. VALIDATION OPTIONS • Compare API capabilities against UI wireframes • Build simple mock interfaces in a micro-framework • Write example code showing how to use it • Write the end user documentation @CaseySoftware
37. AGENDA • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
38. Don’t: Assume you know all use cases @CaseySoftware
39. Don’t: Collect or Share Extra Data • Cambridge Analytica • Why should people to share this information? • How might Keith a bad actor use this information? • You can’t leak what you don’t have @CaseySoftware
40. Don’t: Leak your own Data • What can I tell from using your API? • Do the URLs tell a story? • Does that put customers at risk? • Does it share internal company data? @CaseySoftware
41. Don’t: Roll your own Encryption • Use an existing library that implements an open standard, audit if you prefer • Don’t create your own encryption • No, don’t. You’re not special. • No, not even then. Are you even listening? @CaseySoftware
42. RECAP • Assumptions • What is an API? • What are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
43. WHAT SHOULD WE DO? • Understand the user and their goals • Implement APIs according to use cases, not verbs • Move deliberately with intention • Iterate @CaseySoftware
44. WHAT SHOULD WE AVOID? • Don’t try to do the whole thing at once • Don’t collect/share data the use case doesn’t need • Don’t leak system/implementation details • Don’t implement your own “encryption” @CaseySoftware
45. API DESIGN IS NOT JUST NOUNS & VERBS D. Keith Casey Jr keith@caseysoftware.com / keith.casey@okta.com @CaseySoftware