apidays Paris 2024 - Five Essential Design Assets for Successful APIs, Mike Amundsen

Five Essential Design Assets for Successful APIs
Mike Amundsen, Author of "Design and Build Great APIs", API Strategist & Advisor - amundsen.com, Inc.

apidays Paris 2024 - The Future API Stack for Mass Innovation
December 3 - 5, 2024

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Five Essential API Design Assets Mike Amundsen @mamund
3. API Lifecycle
4. API Lifecycle
5. API LIfecycle
6. Design Assets
7. Design Assets Design assets are any digital resources that are created or used in the design process. -- Uxcel https://app.uxcel.com/glossary/assets
8. Five Essential API Design Assets
9. Five Essential API Design Assets Story
10. Five Essential API Design Assets Story Vocabulary
11. Five Essential API Design Assets Story Vocabulary Diagram
12. Five Essential API Design Assets Story Vocabulary Diagram Description
13. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
14. Let's go …
15. Five Essential API Design Assets Story
16. API Story "Every great design begins with an even better story." -- Lorinda Mamo https://womenforwomen.com.mt/lorinda-mamo/
17. API Story "Every great design begins with an even better story." -- Lorinda Mamo https://womenforwomen.com.mt/lorinda-mamo/
18. API Story • APIs start with a story ◦ "We need…" ◦ "Our customers requested…" ◦ "I have an idea…" • Stories are shared understanding ◦ Our brains are wired for stories, not data ◦ Stories are accessible ◦ Stories are repeatable
19. API Story
20. Good API stories are accessible
21. Five Essential API Design Assets Vocabulary
22. API Vocabulary "Vocabulary is a matter of word-building as well as word-using." -- David Crystal https://en.wikipedia.org/wiki/David_Crystal
23. API Vocabulary "Vocabulary is a matter of word-building as well as word-using." -- David Crystal https://en.wikipedia.org/wiki/David_Crystal
24. API Vocabulary • All the "magic words" related to the API domain • Not just the properties: ◦ id, givenName, etc. • Also : ◦ Actions (create, approve, save, etc.) ◦ Enumerators (status.active, status.inactive) ◦ Containers (item.id, item.givenName, etc.) ◦ Resources/Topics (home, collection, item)
25. API Vocabulary
26. Good APIs have a robust vocabulary
27. Five Essential API Design Assets Diagram
28. API Diagram "We are visual creatures" -- Steven Pinker https://en.wikipedia.org/wiki/Steven_Pinker
29. API Diagram "We are visual creatures" -- Steven Pinker https://en.wikipedia.org/wiki/Steven_Pinker
30. API Diagram • Visual representation of the API • Not .. ◦ a state diagram ◦ a flow diagram • An interaction diagram
31. API Diagram
32. Good API diagrams make connections visible
33. Five Essential API Design Assets Description
34. API Descriptions "Science is descriptive, not prescriptive; it can tell us about causes but it cannot tell us about purposes." -- Jonathan Sacks l https://en.wikipedia.org/wiki/Jonathan_Sacks,_Baron_Sacks
35. API Descriptions "Science is descriptive, not prescriptive; it can tell us about causes but it cannot tell us about purposes." -- Jonathan Sacks l https://en.wikipedia.org/wiki/Jonathan_Sacks,_Baron_Sacks
36. API Description • Why "Descriptions"? ◦ The complete design in one place, in one voice. • Who uses descriptions? ◦ Architects, Designers, Developers, Test, Security, etc. • Time Traveling w/ descriptions ◦ Options for the future, replays for the past • Interaction-centric and Operation-centric
37. API Description
38. API Description
39. API Description
40. API Description
41. Good API descriptions provide the "what", not the "why"
42. Five Essential API Design Assets Definition
43. API Definitions "Most controversies would soon be ended, if those engaged in them would first accurately define their terms, and then adhere to their definitions." -- Tryon Edwards l https://en.wikipedia.org/wiki/Tryon_Edwards
44. API Definitions "Most controversies would soon be ended, if those engaged in them would first accurately define their terms, and then adhere to their definitions." -- Tryon Edwards l https://en.wikipedia.org/wiki/Tryon_Edwards
45. API Definition • API definitions translate design into implementation • API definitions are implementation-specific ◦ OpenAPI (HTTP) ◦ AnsycAPI (Event-Driven) ◦ ProtoBuf (gRPC) ◦ SDL (GraphQL) • Usually API definitions power "generators" ◦ Code ◦ Diagrams ◦ Documentation
46. API Definition
47. API Definition
48. Good API definitions are explicit
49. And so …
50. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
51. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
52. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
53. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
54. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
55. Five Essential API Design Assets Story Vocabulary Diagram Description Definition
56. Five Essential API Design Assets "Design is thinking made visible." -- Saul Bass l
57. Five Essential API Design Assets Mike Amundsen @mamund
58. Five Essential API Design Assets Mike Amundsen @mamund