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.

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