The 5 dimensions of API consistency

Arnaud Lauret

May 23, 2023

API governance often rhymes with consistency because consistent APIs significantly maximize the value generated by APIs. But achieving the creation of APIs at scale requires understanding all possible “API consistency” dimensions.

To create consistent APIs, you must have these five dimensions in mind:

1. Within an API
2. Across the organization
3. With the domain practices
4. With the rest of the world’s practices
5. With standards

Let’s dive into the what and why behind each.

1. Being consistent within the API

The first and crucial step toward API consistency is ensuring each API is consistent within itself. For example, users must be able to easily connect the dots between inputs and outputs and between operations. If a “create account” operation has an accountNumber in its inputs, avoid renaming it as accountId in the response. If this “account number” is used for another “transfer money” operation, don’t rename it like sourceId, which does not give a hint that it is an “account number.” Also, don’t dare change its type from integer to string; it will completely lose users.

2. Being consistent across the organization

It’s indeed essential that APIs share familiar looks and behaviors across an “organization,” which could be a team, business line, or a whole organization. Once users have learned to use a first API, they can use the next one faster, leveraging their experience. You must carefully consider this dimension of consistency because trying to be too consistent across too broad of a scope can make API creation extremely difficult. Sharing high-level behavior is usually okay. For instance, you may use the same design pattern for all “search something” operations across all APIs. But enforcing a shared “customer” model for all APIs dealing with a “customer” will probably be counterproductive if a customer in business line A is entirely different from one in business line B. And it may make sense within a business line to share such a model. You must find a balance to ensure an efficient level of consistency at all organizational levels: efficient for consumers and providers.

3. Being consistent with the domain practices

The subject matter or business domain covered by an API often has more or fewer conventions. You must carefully evaluate those conventions and find balance because brutally exposing a domain’s practices may lead to APIs that are not easy to understand and use for the non-expert, and oversimplification may lead to inaccurate APIs.

4. Being consistent with the rest of the world’s practices

Consistent APIs make people feel smart because people know how to use them based on their past experiences. To foster that type of experience, it’s better to look at the most common practices and copy them instead of reinventing the wheel. But if you already have your wheel and it’s working well, take your time before spending unnecessary time refactoring hundreds of APIs.

5. Being consistent with standards

Following common practices is nice to make people feel smart, but they are sometimes blurry, and there may be different valid common solutions to the same problem. Following standards will ensure users have no surprises. A REST operation that returns an HTTP status 404 Not Found is not only following common practice, it’s also following the HTTP protocol to the letter. And beyond HTTP, you can leverage many standards to make your APIs consistent with many others and interoperable with many tools because they leverage the same standards. For example, designing input and output messaging following the ISO 20022 standards is essential if you work in the financial industry. But be careful; those standards are not always user-friendly for non-experts. ISO20022 will speak to people and tools who have been in the banking ecosystems for decades, but newcomers may prefer less standard but more user-friendly formats.