Many API programs begin as a single API. Over time, more APIs emerge across the company. Consistency for your API consumers – whether they are internal, partners, or public developers – is an important component of a great developer experience. A common design approach makes integration more intuitive and can reduce troubleshooting and support cost.
However, style guides often bring with it the need for centralised governance and migration paths for existing APIs that do not meet guide recommendations. How do you balance all of these concerns, without strict enforcement and negative consequences for API consumers?
In this article, I’ll share some details about what makes a great API style guide, how to avoid the one-size-fits-all mistake, and some techniques some of my clients are using to drive toward consistency without requiring unnecessary governance processes.
What goes into an API style guide?
Great style guides go beyond basic design decisions to include common error strategies, applying patterns consistently across APIs, and even suggest common architecture styles for teams looking to get started quickly.
An API style guide commonly includes the following topics:
- Introduction – the scope of the style guide, who to contact for questions, clarifications, or enhancements
- API fundamentals – used to educate and coach those less familiar with the basics
- Standards – naming conventions, guidance for selecting HTTP methods and response codes, organizing resource paths, resource lifecycle design, payload and content formats, when and how to use hypermedia
- Design patterns – common patterns designers encounter: pagination, error responses, bulk processing, singleton resources
- Lifecycle management – recommendations for moving an API into production, along with deprecation and sunset procedures
- Tools and technologies – list of tools that are recommended, including those with site licenses already available
- Operational recommendations – recommended API management tools, configurations, processes, marketing recommendations, and common practices for highly available, robust, and resilient APIs
- Further reading – additional resources that may be interesting to the reader, including both internal and publicly available papers, articles, and videos
How do we avoid the one-size-fits-all mistake?
Too often, style guides are used to push an agenda. Full compliance…or else. That isn’t what style guides should be about. Their goal should be to advise teams designing APIs toward a more consistent API with other APIs across the organization. A newly hired developer should be able to work with a variety of APIs across the organization without realizing that different teams designed them.
Yet, style guides, without some kind of incentive to adhere to the recommendations, will be ignored. How are companies meant to enforce style guides without a dictatorial approach? I’ve seen three common methods:
- Incentivised – a centralised team oversees and enforces the guide. Reviews are conducted by the centralised team for any new API, prior to production deployment. API teams are incentivised to adhere to the style guide to gain access to shared services and support rather than being forced to implement it themselves, e.g. API management layers, operational support.
- Federated – a centralised team oversees and maintains the style guide, but coaches embedded locally within the business unit and/or region are available to address their specific needs. This avoids the ivory tower problem of a committee designing standards without understanding the needs of specific business units
- Clone and Customise – A single group manages the style guide. Teams clone the standards as a starting point, making minor enhancements locally for business unit consistency. For organisations that have many, independent teams within and/or across business units, this is the most effective
These methods may be used independently or in combination to achieve the desired results that best meet the needs of your organisation.
Should the tone of the style guide be formal?
Some style guides are informal, while others are very formal including the use of RFC 2119 for requirement levels. Which tone should you use? I recommend the tone based on the following questions:
- Will you be enforcing the standard? If so, then use RFC 2119 to enforce what MUST, SHOULD, and MAY be implemented
- Are you currently not enforcing the standard today, but plan to in the near future? Then go ahead and start using RFC 2119, but preface the guide as a common ground for design principles rather than strict enforcement. This will provide guidance for teams designing APIs today, even if there will be no direct enforcement for some initial period
- Are you sharing this across an organization for which you have no control over, or cannot strictly enforce? Then soften the tone and encourage consistency by adopting as many of the guidelines as possible, rather than using a more formal tone
How can I get started?
I would recommend a few steps to get started:
Browse Arnaud Lauret’s (aka the API Handyman) API Stylebook. The API Stylebook aims to help API Designers to solve API design matters and build their API design guidelines. You can browse other publicly available style guides as well, providing insight and even a starting point for your own.
Start small. The scope of an API style guide may be too much to take on initially by one individual or a small team. Start simple and expand as you are able.
Socialise the style guide. Just because you created it doesn’t mean people in your organisation know about it. Spend time evangelising your style guide with teams. Gain their insights from early release candidates, before you release an official version.
Remember: Your goal should be to advise teams designing APIs toward a more consistent API with other APIs across the organisation.
