How to increase adoption of an API style guide

API style guide adoption across an organisation is critical to producing consistently-designed APIs. Without widespread adoption, designs will lack consistency across the portfolio of APIs produced by the organisation. The approach to authentication and authorisation will vary between APIs. Naming conventions and error responses will deviate. In short, the API program will become a mess.

How does an organisation improve API style guide adoption to prevent this from happening? There are several factors involved in gaining adoption of an API style guide. In this article, we will examine these factors and identify some strategies to overcome challenges along the way to gaining API style guide adoption across the organisation.

Establish a clear goal for the API style guide

Without a style guide in place, teams will be forced to make a large number of micro-decisions regarding API style. While this may seem like a minor issue, just remember that every team will have to do the same thing, wasting considerable time and effort.

The goal of an API style guide should be to help increase the speed API teams by making default style decisions easy and deviation easier when it becomes necessary. It will guide teams designing APIs toward a more consistent API with other APIs across the organisation. A newly hired developer or an external partner should be able to work with APIs across the organization without realising that different teams designed them.

Organisations should avoid style guides for the purposes of enforcing a rigorous design review process under the guise of being compliant with the style guide. That isn’t the primary goal of the style guide, although it might be used to drive consistency for the benefit of the API consumers. I’ve seen some organisations that force a rigid compliance process for their API designs result in teams doing whatever they could to skip the review process and exposed the organisation with insecure APIs that open them up for potential harm.

Be clear about the goals of the API style guide and why it should be followed. Implement automation to make it easy for the teams to do the right thing the first time. To learn more, refer to our article “How to create an API style guide, and why”.

Strategies for API style guide implementation

An organisation’s approach to implementing a style guide will vary. Below are three of the most common implementation strategies that you may wish to consider:

  1. Migration Strategy – Teams that already own an API in production won’t be able to adopt it immediately. New work should apply the style guide, but previous APIs will remain as-is to avoid breaking their API consumers. This is the most common for organizations that have been actively promoting their APIs already but want to migrate to a more consistent set of APIs over time. However, this often requires more time to align a large set of APIs to the same style guide as teams may delay their adoption of the full style guide
  2. All-or-Nothing Strategy – Design reviews are conducted by the centralized team for any new API and must pass style guide compliance prior to production deployment. Often, automation becomes important to ensure that teams are able to identify and correct a design element that deviates from the style guide. The same automation may become part of the CI/CD pipeline to force compliance before deployment. This is the most difficult to implement due to the heavy-handed nature of the approach and also will diminish style guide adoption in the short-term
  3. New Version Strategy – Teams implement the style guide elements upon a new major version of their API. This allows for “grandfathering” current versions of an API that do not follow the style guide, but requests that new versions follow the style guide whenever possible. This is a nice blend of the two previous strategies that will increase API adoption and will drive to a more consistent set of APIs in a shorter amount of time

Of course, your implementation approach might take elements from each of these strategies to find the right mix for your organisation.

Adjust the style guide tone to increase adoption

An underused technique for increasing style guide adoption is to adjust the tone of the style guide. While many suggest that an API style guide should follow the RFC 2119 language of MUST, SHOULD, and MAY, this is not necessarily a requirement. Deciding upon the tone and formality for the style guide can have a positive (or negative) adoption result.

The style guide should offer guidance where teams need it, but allow for deviations where it makes sense. This may be expressed as part of an RFC 2119 approach where the majority of the focus is on the SHOULD and MAY elements, with a few MUST elements where there should be absolutely no compromise.

However, a formal language approach may be too heavy-handed for the current state of the organization. This is particularly the case when an organisation is emerging from a historically-rigid governance approach where rigid contracts supercede improved developer experience. In this case, start with using the RFC 2119 language but do not capitalize them indicating enforcement. The tone of the API style guide will shift from compliance to guidance and allow time for the organization to shift to a more positive focus on developer experience through API consistency rather than heavy-handed enforcement.

Increase adoption by starting small

Style guides should start with a small set of guidelines and expand over time. Consider starting first on naming and syntax concerns. Perhaps offer a recommendation for versioning and some useful defaults to help teams get started.

Socialise the style guide and begin to gather feedback. Start to apply the style guide to new APIs and incorporate feedback and clarifications. Refine the style guide and expand it as needed, including the addition of some alternative considerations when a single approach isn’t universally appropriate. Over time, the guide should extend to common error strategies, applying patterns consistently across APIs, and suggest common architecture styles for teams looking to get started quickly.

Start with a Single API style

Some organisations take advantage of more than one API style. Perhaps REST is the preferred style, but GraphQL and gRPC may be used under certain circumstances. This can lead to a monumental effort to capture API style guidelines for every supported API style before rolling out the guide.

It is important to focus on one API style first and then add support for new styles over time. Apply the same lean delivery approach you might use for a product release schedule. Release, gain feedback, and improve based on the learnings.

I recommended to write a style guide for each API style at the start. Over time, common recommendations such as naming conventions and reserved words may be shared between API style guides. However, most organizations find that there is significant deviation in standards and common practices across API styles. In fact, some may recommend lowerCameCase for property names, while other API styles may prefer snake_case naming conventions, making it difficult to reuse across style.

Remember that it is better to follow common practices for each API style rather than trying to unify all API styles into a single set of recommendations. To put it another way, we shouldn’t require Java code to start using snake_case just because the organisation also supports coding in Python. Trying to unify the style guide across multiple API styles will result in confusion and frustration. Finally, keep in mind that some API styles depend upon tooling that expects certain style conventions.

Style guide adoption takes time

Unless you manage a small team, it takes time for a style guide to gain adoption across an organisation. The strategies and tips provided in this article provide some ideas for how to approach the adoption of your style guide. It may require taking a slower approach than you had planned. Or, perhaps it requires that you rethink your approach entirely. Whatever you decide, remember that the goal is to empower teams and reduce their burden to come up with their own style guide by avoiding the many micro-decisions throughout all aspects of their API design process. It will also produce a more consistent set of APIs that will make it easier for customers, partners, and the workforce to work with your APIs.