The 3 fundamental checks of API governance rules

Arnaud Lauret

August 7, 2023

API definitions, such as OpenAPI documents, are often inspected to perform automated API governance checks. As an API definition aims to describe an API interface contract, one may only focus on API governance rules targeting this aspect. But fundamentally, there are three types of information you can verify in an API definition: the actual interface contract, the metadata, and how the API specification is used. Let’s see what you can get by investigating these three different aspects and how they can contribute to the real purpose of API governance: helping people easily create APIs that will generate the maximum value.

Related: Enterprise best practices: successfully govern your API content and users

1. Checking the actual interface contract

The very first aspect you’ll want to check within an API definition is the actual interface contract it formally describes. That covers all elements that will be used or exchanged during API calls: i.e., resource paths, HTTP methods, HTTP status codes, or data models.

With API governance rules performing checks on the actual interface contract, you can:

• Promote the creation of interoperable APIs by avoiding going against standards such as the HTTP protocol when you verify that a GET request doesn’t include a request body or an HTTP 204 No Content doesn’t return some content.
• Foster the creation of user-friendly APIs by detecting inconsistent casing in parameter, or property names, questioning the use of required query parameters, or proposing to replace someProperty1, someProperty2, and someProperty3 with a someProperty array.
• Secure your API by ensuring all operations are linked to at least one security definition, scopes are defined, or requesting API creators not use less-secured security modes (like API keys) or only use a specific security mode (like bearer tokens).
• Limit performance issues by ensuring there are pagination and search filters on search operations or that standard HTTP cache mechanisms are defined.
• Reduce the risk of later breaking changes for your APIs by promoting the use of objects for request and response bodies instead of arrays or atomic types such as string or question properties that are an array of atomics (an array of numbers, for instance).
• Facilitate API monitoring by ensuring only selected HTTP status codes are used; unexpected HTTP status codes may trigger unnecessary alerts.

2. Checking the API metadata

Though a well-designed API interface contract may be self-explanatory, an API definition should contain metadata giving more context about what the API is and how to use it. The bigger and most obvious part of this metadata relates to documentation with summaries and descriptions. But metadata may also cover configuration elements not part of the actual contract; for instance, an operation ID is a piece of metadata that can be used for code generation or API gateway configuration.

With API governance rules performing checks on metadata, you can:

• Reduce the risk of creating the wrong APIs by requesting the name of the API not be simply “API.” That will make the API designer wonder what its purpose is and set its boundaries to avoid the later addition of operations out of the scope of the API. Also, having the owner of the API provide their contact name may help ensure the right person makes the right decisions for the greater good of the API.
• Facilitate understanding by ensuring operation summaries are provided (with operations organized by tags), verifying response descriptions are not just HTTP reasons but helpful descriptions explaining what is happening, or questioning the absence of descriptions on properties (because sometimes the context, name, and type are not enough).
• Speed up time to value by ensuring examples are provided, especially on request and response bodies, so mocks can be generated to facilitate feedback during design or help consumers build their applications faster without relying on the actual API.
• Ensure the generation of user-friendly code by checking operation IDs are provided and unique, so code generators can create user-friendly methods.

3. Checking how the API specification is used

The same interface contract may be described in different ways using a format such as OpenAPI. How the API specification is leveraged may have impacts on its consistency, maintainability, and also its user-friendliness.

With API governance rules performing checks on the API specification usage, you can:

• Enhance user-friendliness and maintainability by ensuring request and response bodies are defined via reusable data models, or all 4XX and 5XX responses use your standard error model.
• Ensure tool compatibility by checking no unsupported feature of the API specification is used.

Don’t focus on a single aspect

As you can see, while the interface contract is the most visible part of the API definition iceberg, by only focusing on it, you may miss important underlying aspects contributing to maximizing the value that can be created by APIs. Ultimately, automated API governance checks and API definition linting can cover many important bases in the API lifecycle—simplifying and speeding up the whole process of creating, maintaining, and using high-quality APIs.