In our recent post on tips for starting a public API journey we touched briefly on the idea of creating a style guide that helps API providers produce well-constructed and consistent APIs as part of their public API offering. The creation of an API style guide is, however relevant for API providers regardless of whether they are providing APIs externally or internally: It provides the context for their development efforts whether it be outsourced or created internally and is an important tool for achieving some level of governance across the organization.

In this post we’ve taken a more detailed look at what a style guide might contain and how it might be enforced.

General Approach

The primary function of an API style guide is to give the developers in your organization direction on how to craft their APIs, including any requirements on the construct of the API and the features that it implements. In terms of a general approach, the tone of a style guide can fall anywhere on a spectrum between authoritarian and autonomous, with developers granted freedom of choice relative to it. Each approach has implications for how APIs will be written and published within an organization:

• An authoritarian approach is a top-down style guide, dictating how developers should design and build their APIs and mandating the vast majority of their approach. This kind of guide is most likely to be implemented in organizations with a ‘strong’ architectural governance function and a reasonably homogenous approach to software development; they are likely to be incorporate exhaustive design principles such as the style of the recently released Microsoft API guidelines. This approach has benefits where organizations need to be prescriptive in how APIs are developed to achieve a determined level of consistency, which benefits developer experience for API consumers but clearly limits freedom of choice for developers in creating an API. Enforcement of the style guide will most likely come from committee-style review processes and a gated promotional model;
• The autonomous approach is a more bottom-up style guide, with general guidelines for ensuring that API development results in APIs that can be described, provided and exposed or discovered without focusing too hard on how to achieve it. This approach is analogous with the aims of the Spotify Engineering Approach, with the goal of ensuring teams are aligned with organizational direction but able to use their initiative when actually building the APIs they are responsible for. Enforcement of the style guide in this decentralized environment is therefore likely to be owned by the teams themselves, with API design review being part-and-parcel of the teams working practices and possibly incorporating continuous integration features that automatically check the semantics of the API when a build is triggered,

On reading these two descriptions one may feel that the autonomous approach is “better” than authoritarian approach, but actually the definitions are not designed to convey a sense of best practice: They simply acknowledge the fact that every organization is different and will need to approach API development accordingly. For example, in organizations that regularly outsource software development it will be advantageous to have an authoritarian style guide, as this can be easily incorporated into the obligations placed on the supplier and form part of the contract.

With the general approach in mind, there are several key areas that a style guide must cover, namely: Construct, Description, Data, Encoding, Links, and Versioning. While this list is not intended to be exhaustive, these are the areas that are likely to have the most impact on the creation of APIs in your organization.

Construct

Construct is a catchall that covers the fundamental building blocks of an API. Probably the most important are:

• Resources (URIs);
• HTTP methods;
• HTTP headers;
• Query parameters;
• Return codes.

Anyone who looks at these five areas and are experts in HTTP and REST APIs would argue that all of these are designed for specific purposes and clearly should only be used with those purposes in mind; there would certainly be a perception by many that REST is well, REST. However, it’s quite possible that many developers creating your API won’t know (and in some cases won’t really care) about the distinctions or the fundamental principles of REST; many will just see pragmatic ways to get their job done, often based on their previous knowledge and experience, and will choose an approach accordingly.

The job of the style guide is therefore to detail when and how to use each of these: It limits interpretation where limits need to be set. An example set of guidelines might be:

• Resources should describe the “objects” that your API describes, with an identifier that uniquely identifies each object;
• HTTP methods are used to “change” the state of the object, with a mandated list of supported methods;
• HTTP headers are used for passing mandatory arguments such as for authentication, accepted content types, etc.;
• Query parameters are used for optional arguments and can be omitted as required;
• Return codes should mirror the meaning and semantics of the core HTTP specification, ensuring the code is informative and embellished with extra information in the payload where required.

The idea of such guidelines is therefore to clearly layout for developers how to treat each of these types of construct: To define what it is for and how to implement it. The more authoritarian style guides will dive into areas such as exact resource constructs and allowed HTTP headers, therefore leaving little doubt in the developer’s mind.

Description

Alongside standardizing description, an organization’s style guide should also define how their APIs are described; the two subjects actually complement each where an organization looks to use API-first design, given that developers will be actively considering how to describe their APIs prior to writing any code.

However, to describe an API an organization needs to define a method for doing so and the style guide should help the developer by defining the expectations. On one end of the spectrum, an authoritarian guide will mandate a given API description format (OpenAPI, RAML, etc.) and detail organizational standards such as mandatory fields and any custom extensions that are required. On the other hand, an autonomous style guide might define more loose guidelines by simply stating that an API be should be described and then leaving the teams to select their preferred specification; the style guide might also include notes on using API Transformer or api-spec-converter to jump between different specification formats.

It is important also to note that your choice of API description format may also preclude certain design practices; What can be expressed easily in an OpenAPI specification may be impossible to expressed in an API Blueprint specification, for example. Your choice of API description format should therefore complement your style guide as much as possible.

Data, Encoding, and Links

Data, Encoding, and Links form a triumvirate of factors that can mould how the response payload of an API is constructed. As with our other areas, the style guide’s general approach can significantly influence how these areas are defined:

• An authoritarian approach will be explicit with what is and is not permitted to be included, with specific references to the enterprise data model and the provenance of any fields in the payload;
• A autonomous approach, on the other hand, will allow a degree of flexibility, allowing teams to define their payload and data constructs in the manner that best suits them.

Whichever approach prevails, there are some foundational aspects on this subject that should be found in any style guide:

• What data should be returned: For example, how a unique identifier for a given member of a collection should be expressed, support for pagination, filtering of large GETs, etc.;
• What encoding should be supported: The majority of new web APIs tend to implement JSON only, but there are cases where APIs support alternative encoding specifications such as XML. The style guide should define what is mandatory, what alternatives can be implemented, and how to deal with the transposition between different specifications;
• The use of links: Hypermedia APIs have long been considered by many in the industry as being the way to implement data linkages across multiple endpoints or APIs, with identifiers to related data items implemented as links rather than as a simple surrogate or canonical identifier. However, doing so cohesively across an organization demands a singularity of purpose that a style guide can help deliver. Moreover, there are times when including rather than linking to data for the purposes of efficiency is desirable. The style guide therefore needs to define an organizational approach to hypermedia APIs and, where they are being promoted, define practical steps for making them work.

Like the constructs of your API, ensuring consistency across these areas will help ensure ease of use for your API consumers and elicit a level of familiarity whenever they work with one of your APIs.

Versioning

Getting versioning right can have a major impact on the how your API is perceived by your API consumers internally or externally, and can also make the management of your API estate more difficult if it’s ill conceived. Versioning is therefore an important part of a style guide and it’s probably more important to create a policy exhaustively across your organization; if all teams took different approaches as they might in an autonomous model, managing dependencies between APIs across your organization will become very difficult indeed.

A versioning policy should therefore be defined top-down, with clear guidelines on when and why to version your APIs; for example, the significance of breaking changes, use of major and minor versions, and so on. Any flexibility should be granted to teams in the how, allowing them to implement version requests as they see fit (in custom headers, the Accept header or as part of the URI).

Final Thoughts

In this post we’ve tried to focus on what a good style guide should contain and how team structure and organizational approach might influence it. Regardless of technical correctness, the most important aspect of the style guide is to set the tone for API development; it will help define your character as an API provider, and provide a cohesiveness throughout your organization as you undertake your API journey.