Good API design is important! And one of the main aspects of any good design (not just for APIs) is consistency. Developers (or other users) should be able to recognize patterns and not suddenly encounter elements that go against their expectations. The typical approach to enforce consistency between multiple people working on a product or even across teams in an organization is to write down a set of rules - an API style guide.

The problem with rulebooks of any kind, though, is that people don’t like reading them or, even if they do, they cannot remember it all and so they accidentally break the rules. That can be prevented, of course, with automatic validation and linting through tools like Spectral. However, maybe the better approach is not having too many rules to begin with?!

It was the lesson learned by Holger Reinhardt, CTO of Adello. As he wrote on the company’s tech blog, based on his experience of writing an extensive style guide for his previous employer, he tried to limit himself “to the very critical and core aspects of API design”.

The resulting Adello API Styleguide is publicly available. I like how it covers everything that I would also consider essential, provides additional reading material, and references to principles like Postel’s law. However, you can still glance over it in seconds and read the entire thing in minutes. I’m sure that this guide could be a good example that other companies could build their API style guides upon.

By the way: if you think your API design needs improvement and you could use some help, I’m available for API consulting freelance work!