API Design Reviewer's Starter Set

What could go possibly wrong when designing APIs? Everything.
Among many other things, API Design may be inconsistent with pre-existing elements, may be bugged, may not fulfill needs, may be hard to understand or use, may be too specific and impossible to reuse, …

Whatever the organization’s size, the type of APIs and the designers skills and experience, something will go wrong.
That is why, any API design must be reviewed.

During this session, Arnaud Lauret, The API Handyman, author of The Design Of Web APIs, will uncover everything you need to start reviewing the designs of your organization’s APIs.

Explore subterranean needs! Plunder hoards of inconsistency! Battle legendary design flaws!

The API Design Reviewer’s Starter Set is your gateway to exhaustive and constructive API design reviews. This session contains the essential rules of design reviews plus a few tips and trick that will be of great help on your perilous adventures in the API world.

Transcript

2. Twitter: @apihandyman Blog: https://apihandyman.io Book: The Design of Web APIs https://bit.ly/designwebapis (use code ctwapidp19 to get 40% off)
3. Twitter: @apihandyman Blog: https://apihandyman.io Book: The Design of Web APIs https://bit.ly/designwebapis (use code ctwapidp19 to get 40% off)
5. PART X Part Title PART 1 Why API Design Reviews? When you attempt to influence someone [...], the DM might ask you to make a Charisma (Persuasion) check Dungeons and Dragons Player's Handbook
6. PART X Part Title PART 1 Why API Design Reviews? When you attempt to influence someone [...], the DM might ask you to make a Charisma (Persuasion) check Dungeons and Dragons Player's Handbook Persuading audience failed
7. Character sheets Donan The Designer API Designer Level 2 Rena The Reviewer API Designer Level 23 API Design Reviewer Level 5
8. When you use active roleplaying, you speak with your character’s voice, like an actor taking on a role. Dungeons and Dragons Player's Handbook
9. Salutes Rena. Donan the Designer
10. Rena the Reviewer Salutes Donan.
11. Don’t get why his POST /send-email operation has to be reviewed. Donan the Designer
12. Rena the Reviewer Explains review’s purpose and reassures Donan.
13. Wants to know if everything is OK. Donan the Designer
14. Rena the Reviewer Tells form is almost OK.
15. Rena the Reviewer Propose and explains solutions to fix problems based on guidelines.
16. Thinks the review is over. Donan the Designer
17. Rena the Reviewer Tells that form is not all, context is analyzed too.
18. Describes why POST /send-email is needed. Donan the Designer
19. Rena the Reviewer Continues context’s investigation.
20. Describes how POST /send-email is actually used. Donan the Designer
21. Rena the Reviewer Explains why this design is a problem in this context.
22. Realizes his mistake thanks to review. Starts to rethink his plan... Donan the Designer But that’s another story... Persuading Donan succeed
23. So, why do we need API design reviews?
24. So, why do we need API design reviews? Inconsistent Bugged Incomplete Non user friendly Unsecure Not fulfilling real needs
25. So, why do we need API design reviews? Inconsistent Bugged Incomplete Non user friendly Unsecure Not fulfilling real needs Reviewers can help avoid these problems
26. PART X Part Title PART 2 Conducting a Review Read the rules of the game and the story of its worlds, but always remember that you are the one who brings them to life. Dungeons and Dragons Player's Handbook
27. Rule #1 Lifecycle Early Review Cold Review Live Review End Sometimes the journey deserves as much time and attention as the destination Dungeons and Dragons Dungeon Master’s guide Conducting a Review
28. Rule #1 Lifecycle Early Review Early Review Cold Review Live Review End Conducting a Review
29. Rule #1 Lifecycle Cold Review Early Review Cold Review Live Review End Conducting a Review
30. Rule #1 Lifecycle Live Review Early Review Cold Review Live Review End Conducting a Review
31. Rule #1 Lifecycle Cold/Live Cycle Early Review Cold Review Live Review End Conducting a Review
32. Rule #1 Lifecycle Explain process Early Review Cold Review Live Review End Conducting a Review
33. Rule #2 Be exhaustive Your character in the game might explore forgotten ruins and uncharted lands, uncover dark secrets and sinister plots, and slay foul monsters. Dungeons and Dragons Player's Handbook Conducting a Review
34. Rule #2 Be exhaustive Design makes sense and is user friendly Conducting a Review
35. Rule #2 Be exhaustive Design conforms to guidelines and is consistent Conducting a Review
36. Rule #2 Be exhaustive Design is secure Conducting a Review
37. Rule #2 Be exhaustive Design takes limitations into consideration Conducting a Review
38. Rule #3 Make People Talk Exploring dungeons, overcoming obstacles, and slaying monsters are key parts of D&D adventures. No less important, though, are the social interactions... Dungeons and Dragons Player's Handbook Conducting a Review
39. Rule #3 Make People Talk Listen, Question, Comment, Rephrase Conducting a Review
40. Rule #3 Make People Talk Context, Needs, Vocabulary, Concepts, Processes, ... Conducting a Review
41. Rule #3 Make People Talk Refocus on high level Conducting a Review
42. Rule #4 Adopt the Right Mindset Neutral good alignment: Folk do the best they can to help others according to their needs. Dungeons and Dragons Player's Handbook Conducting a Review
43. Rule #4 Adopt the Right Mindset Teach and Explain instead of Shame Conducting a Review
44. Rule #4 Adopt the Right Mindset Empathy for consumers Conducting a Review
45. Rule #4 Adopt the Right Mindset Trust API Team Knowledge Conducting a Review
46. Rule #4 Adopt the Right Mindset Don’t Block Conducting a Review
47. PART X Part Title PART 3 Conducting many Reviews The game has no real end; when one story or quest wraps up, another one can begin, creating an ongoing story Dungeons and Dragons Player's Handbook
48. Rule #1 Fill Your Toolbox Proper equipment can mean the difference between life and death in a dungeon or the untamed wilds Dungeons and Dragons Player's Handbook Conducting many Reviews
49. Rule #1 Fill Your Toolbox API Design Guidelines Conducting many Reviews
50. Rule #1 Fill Your Toolbox Machine Readable API Description Format(s) Conducting many Reviews
51. Rule #1 Fill Your Toolbox API Description Format(s) Tooling Conducting many Reviews
52. Rule #1 Fill Your Toolbox Adapted Design Tools Conducting many Reviews
53. Rule #2 Record Everything No one's memory is infallible, so it pays to keep records. Dungeons and Dragons Dungeon Master’s guide Conducting many Reviews
54. Rule #2 Record Everything Write Reviews Report Conducting many Reviews
55. Rule #2 Record Everything Record Decisions Conducting many Reviews
56. Rule #2 Record Everything Store all Interface Contracts Conducting many Reviews
57. Rule #3 Govern … But Not Too Much As a referee, the DM acts as mediator between the rules and the player Dungeons and Dragons Dungeon Master’s guide Conducting many Reviews
58. Rule #3 Govern … But Not Too Much Governance Level Conducting many Reviews
59. Rule #3 Govern … But Not Too Much Community Conducting many Reviews
60. Rule #3 Govern … But Not Too Much Committee vs Single Reviewer Conducting many Reviews
61. Rule #4 Teach and Train You can spend time between adventures learning a new language or training with a set of tools. Dungeons and Dragons Player's Handbook Conducting many Reviews
62. Rule #4 Train and Teach Propose help on design Conducting many Reviews
63. Rule #4 Train and Teach Propose training Conducting many Reviews
64. PART X Part Title The End
65. PART X Part Title PART 4 Participating to a Review Together, the DM and the players create an exciting story. Dungeons and Dragons Player's Handbook
66. Rule #1 Don’t wait until it’s too late A fast pace makes characters less perceptive, while a slow pace makes it possible to sneak around and to search an area more carefully Dungeons and Dragons Player's Handbook Participating to a Review
67. Rule #1 Don’t wait until it’s too late No badge Participating to a Review
68. Rule #1 Don’t wait until it’s too late Implementation can be hard to fix Participating to a Review
69. Rule #1 Don’t wait until it’s too late Terrible consequences Participating to a Review
70. Rule #2 Be prepared Between trips to dungeons and battles against ancient evils, adventurers need time to rest, recuperate, and prepare for their next adventure. Dungeons and Dragons Player's Handbook Participating to a Review
71. Rule #2 Be prepared Bring All Knowledge Participating to a Review
72. Rule #2 Be prepared Provide user friendly documentation Participating to a Review
73. Rule #2 Be prepared Provide standard & fully documented interface contact Participating to a Review
74. Rule #2 Be prepared Pre-check interface contact Participating to a Review
75. Rule #2 Be prepared Read Reviews Participating to a Review
76. Rule #3 Adopt The Right Mindset Neutral good alignment: Folk do the best they can to help others according to their needs. Dungeons and Dragons Player's Handbook Participating to a Review
77. Rule #3 Adopt The Right Mindset Don’t take it personally Participating to a Review
78. Rule #3 Adopt The Right Mindset Challenge and question reviewer Participating to a Review
79. Rule #3 Adopt The Right Mindset Propose guidelines evolutions Participating to a Review
80. PART X Part Title The End
81. API design reviews make everyone grow If everyone had a good time and created a memorable story, they all win. Dungeons and Dragons Player's Handbook