APIdays Paris 2018 - The Lord of API Design, Arnaud Lauret, API Handyman & API Architect, Natixis
0 likes349 views
This document discusses the importance of consistency in API design and the need for API style guides. It notes that initially one person may design an API, but over time inconsistencies creep in as more people contribute. This leads to wasted time for both users and designers. The document advocates defining a style guide with clear rules that are discussed, shared, and enforced to maintain consistency across an organization's APIs. It also briefly describes tools that can help automate style guide rule validation.
APIdays Paris 2018 - The Lord of API Design, Arnaud Lauret, API Handyman & API Architect, Natixis
- 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
- 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?
- 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?
- 28. Let’s forget what I’ve just doooone!!!!
- 29. … But we needed more and more API designers and things get even worse!
- 33. My precious! More inconsistency! And so much time loosed!
- 34. But what can we do my precious?
- 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?
- 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
- 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
- 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