The Lord Of API Designs

Every company’s API surface grows irremediably. More and more APIs means more and more people designing APIs, therefore keeping a company’s API surface consistent is quite a challenge. Failing this challenge may lead to a less efficient and even be counterproductive.

In this session, based on my own experience defining and sharing API design common practices in my company and based on the API styles guides that I have collected on apistylebook.com, we will discover why we desperately need API style guides, what we can put in them, how to build them and how they can or cannot help us and our fellow API designers to create together a flawless consistent API surface for our company. We will also see how API style guides could be used in the API ecosystem with tools such as the OpenAPI specification and API design tools to ensure that their rules are followed retrospectively and preemptively.

Transcript

1. THE LORD OF API DESIGNS by ARNAUD LAURET, AXA BANQUE @apihandyman apihandyman.io apistylebook.com
2. THE SHADOW OF API DESIGN Chapter I
3. Look at your API design! What happened?
4. My precious API design! What have we done?
5. First API
6. But after that the nightmare started
7. First API updated
8. More and more public and private APIs!
9. Second API
10. Third API ...
11. Fourth API ...
12. Nth API … Nth API
13. What’s the problem with these APIs?
14. /heroes/{bilbo} /characters/heroes/{bilbo} /api/hero/{bilbo}
15. “name”: “FirstnameLastname”: “character-name”: “character_name”: “fnLn”: “Baggins, Bilbo” “Bilbo Baggins” “bilbo baggins” “BILBO BAGGINS” “B. Baggins”
16. URL Naming Case Data structures Security Parameters Error messages HTTP status codes Behaviour ...
17. My precious! Too much differences! Too much inconsistency!
18. Inconsistency Between APIs And inside a single one
19. But what’s the problem with inconsistency?
20. Why do you almost always know how to open a door?
21. Why Gandalf hates Moria’s door?
22. One does not simply use inconsistent APIs
23. Using each new endpoint or API is a totally new adventure
24. Users and their software hate inconsistent APIs
25. So much time lost! So much users lost! So much money lost!
26. Is that the work of a single API designer?
27. At the beginning yes…
28. Let’s forget what I’ve just doooone!!!!
29. … But we needed more and more API designers and things get even worse!
30. Endless discussions
31. Repeated endless discussions
32. Let’s reinvent the wheeeeeel!
33. My precious! More inconsistency! And so much time loosed!
34. But what can we do my precious?
35. A LONG-EXPECTED API STYLEGUIDE Chapter II
36. This is API design There are rules Defined in an API Styleguide
37. How APIs look and behave
38. How to design APIs
39. How to create but also update an API
40. How to handle the API lifecycle
41. All needed rules to ensure consistency
42. Rules discussed once No more time loosed Focus on what’s really important
43. Rules applied to all APIs No more inconsistencies
44. Both users and designers are happy
45. So all we have to do is describe rules in a styleguide?
46. THE BATTLE OF THE API STYLEGUIDE Chapter III
47. Write
48. Rules based on your existing APIs or others
49. Based on existing API styleguides apistylebook.com (shameless plug)
50. And don’t forget your fellow API designers
51. And it’s done?
52. No, it’s only the beginning
53. If a book is not read, does it exist?
54. Share and promote
55. What else?
56. API styleguide will need to evolve
57. Update Improve
58. Is that all?
59. One last thing
60. Rules may not be followed
61. Enforce and control
62. Is this control only done by people?
63. Mostly but some try to automate part of these controls...
64. THE API DESIGN HAVENS Chapter IV
66. Machine readable API description
67. Zalando’s Zally A minimalistic API linter https://github.com/zalando-incubator/zally
68. Rule #174 is violated
69. Rule #174 is defined in guidelines
70. There’s also an API and a CLI
71. You can define your own rules
72. So, no more humans?
73. Such tool really helps But we still need humans
74. THE FELLOWSHIP OF API DESIGNERS Epilogue
75. “Good” API Design is nothing without consistency
76. No consistency without clearly defined rules
77. Rules are nothing without governance (establish, share, update, control)
78. It’s time to build your fellowship of API designers
79. THE END THE LORD OF API DESIGNS by ARNAUD LAURET @apihandyman