Seven must-haves for your API design style guide

Do you want to design awesome APIs? Consistency across all the APIs in your API portfolio is key.

And consistency makes your APIs intuitive for developers to use, and that’s what developers like. Because, instead of reading through a bunch of documents, they can use your APIs intuitively, because the APIs are consistent. In other words, this API works the same way as the last API, just as they would expect.

But ensuring consistency in a large organization is actually more difficult than you would expect. There are many designers and so many design decisions that contribute to the consistency of an API. To ensure consistency, it is best practice that each organization creates and follows an API design style guide, that sets some rules for the design of an organization’s APIs.

API design style guide

An API design style guide helps designers and developers build consistent APIs across their API portfolio. It is helpful because designers and developers have a lot of things to think about, lots of choice, and many design decisions to make when designing an API. But not all design decisions are created equal.

I see three categories of design decisions:

1. Some of these design decisions are driven by the functional requirements of the API. The data served by the API or the functionality exposed by the API dictate those design decisions.
2. Other design decisions impact non-functional properties, such as decisions regarding security, and you may want to set a certain quality level.
3. Then there are design decisions that are more arbitrary, there is no right or wrong, just lots of opinions – a true matter of style and personal preference like how you name URLs, parameters and resources, how you deal with collections and lists etc.

Which categories of design decisions should an API design style guide cover?

1. Functionality is API specific – and cannot be standardized or covered in a style guide. 
2. Non-functional properties are often overlooked. You should include them in a style guide to ensure minimum quality levels. 
3. Arbitrary design decisions are what style guides are made for. A style guide is most useful for these types of decisions. 

An API design style guide should mainly cover design decisions of the last category.

Even more concretely, I recommend you cover the following seven topics:

1. Naming conventions (e.g., resources, URLs, parameters)

There are two aspects to naming:

(A) The same data should have the same name consistently across your API portfolio. If we call it “personal address” in one API and just “address” in the other API, but it refers to the same data, we should also call it the same. An overarching domain model for the company can be very beneficial towards this goal.

(B) Use the same syntactic rules to construct variable names, URLs and parameters, e.g., using snake_case, camelCase, lowercase etc.

2. Collection handling

When the response payload of an API contains lists or arrays (collections), make sure the developer can interact with these lists consistently. There should be a common way for sorting collections, filtering or searching collections, and paging through collections with many elements. If collections can be written to, there should also be a consistent way for adding, replacing or deleting elements in collections.

3. Authentication & authorization

The authentication & authorization step is a typical stumbling block for developers, especially if each API in a portfolio uses different mechanisms, tokens and processes. Stick to a few mechanisms for the most common use cases, e.g., access to end-user data requires OAuth2, and access to non-critical client data requires API keys as a minimum.

4. Status codes & error handling

If an error occurs in an API, no one is happy. Make it easy for developers to find out what went wrong. Use consistent status codes, error descriptions, with helpful metadata (often a tradeoff with security) such as those described in RFC 7807.

5. Response headers and formats

Do you deliver your API responses “pretty-printed” with white space in them? Or do you save a few bits and trim all white space? What is the default for your CORS and caching headers?

6. Versioning

All your APIs should be updated and deprecated in the same way. Include versioning rules in your style guide, such as:

• Apply version numbering to each API, starting with the very first publication of the API.
• Explaining the numbering scheme, e.g., with minor (non-breaking) and major (breaking) versions.
• Decide whether you want to include version numbers in URLs or only in API headers.

7. Long-running operations

REST is made for a request-response scheme, where the response is delivered almost immediately after the request. But often API calls need to trigger long running operations, such as batch jobs that work in the background and eventually deliver their results. Define one mechanism for pressing long-running operations into the request-response scheme and document it in the style guide.

Some practical tips for working with an API style guide

• Don’t let strong opinions about API style escalate. Remind everyone that having a style guide that everyone adheres to is more important than the actual content. 
• If you don’t have a style guide yet, or start a new API portfolio, you do not need to also write your style guide from scratch. Instead, start with copying an existing style guide, like Google. 
• To improve the acceptance of your style guide, publish it on your developer portal. It creates (a good kind of) pressure for APIs to be consistent with the style guide.
• To further improve acceptance and widen the use of the style guide, you can operationalize the style guide and implement it in the form of a validation tool. This can actually be done without much effort, if you base the validation on the OpenAPI spec and a linter tool.

I hope this inspires you to create (and use) an API design style guide of your own – and gives you some practical tips and tricks to get started. Your API consumers will appreciate your consistent and intuitive API design, as it is an important part of a great developer experience for the users of your API.

Learn more about how to create a great developer experience beyond the portal by clicking below