The word “governance” often puts development teams off, and one can see why. In many organisations it means a monthly committee, a standards document dozens of pages long that nobody has read in full, and a form to fill in before anything can be published. The result: rules are bypassed, or applied unevenly, and governance becomes a brake without being a guarantee.
There is another approach, which we put into practice regardless of the gateway or integration platform: a small number of rules, checked automatically, at the moment of deployment.
What governance must actually guarantee
Before writing a single rule, it is worth asking what one is trying to prevent. In most contexts, the list fits in a few lines:
- an API exposed without authentication;
- an API whose owner nobody can name;
- a change that breaks consumers without warning;
- an API in production that does not match what was approved;
- sensitive data exposed without anyone having decided that it should be.
Everything else (naming conventions, path style, date formats) is useful, but secondary. Confusing it with the essentials is the first cause of bureaucracy.
Principle 1: a rule that is not checked automatically does not exist
A standard written in a document is applied only when someone remembers it. We turn every important rule into an automatic check run by the deployment pipeline:
- the contract (OpenAPI, WSDL or AsyncAPI) is validated by a linter with a versioned rule set;
- the policy description is checked: authentication present, traffic limit defined, owner recorded;
- the contract is compared with the previous version to detect breaking changes.
These checks are code: versioned, reviewed and tested like everything else. This is often called policy-as-code: the term matters little; what matters is that the rule actually runs.
Principle 2: refuse rather than observe after the fact
A dashboard that lists non-compliant APIs in production comes too late: the API is already exposed. We place the critical checks before deployment, and the pipeline refuses to deploy an API that does not meet them. This is a fail-closed stance: when in doubt, block.
That requires two safeguards:
- blocking rules must be few and beyond dispute, otherwise teams will look for ways around the pipeline;
- there must be an explicit exception process, traced and time-limited, rather than a silent disabling of the check.
Less critical rules can remain warnings: they appear in the merge request, without blocking.
Principle 3: compliance must also be checked afterwards
A compliant deployment does not guarantee that production stays that way. A manual change in a console, an emergency fix or configuration drift can make the environment diverge from what was approved. Hence two complementary checks:
- after every deployment, reread the actual state and compare it with the expected state;
- periodically, compare the whole environment with the repository and flag any discrepancy.
An API whose production definition no longer matches what was approved is no longer governed, even if it was on the day it went live.
Principle 4: ownership is data, not a tick-box
“Who is responsible for this API?” is the question one asks at the worst moment, in the middle of an incident. We make this field mandatory in the description of every API, with a team and a way to reach them, and the pipeline rejects an API without an owner. It is a simple, inexpensive rule that proves its worth.
Principle 5: contract breaks are negotiated beforehand, not afterwards
An incompatible change (a field removed, a type changed, a path renamed) is not forbidden, but it must be visible and deliberate:
- the pipeline detects the break by comparing the contract with the previous version;
- a break requires a new major version, or an explicit approval;
- the previous version remains available during an announced transition period.
We recommend a transition period defined with the teams, depending on the context.
What a starting rule set looks like
To get started, we generally propose a short baseline:
- blocking: authentication declared on every exposed API;
- blocking: owner recorded;
- blocking: contract syntactically valid;
- blocking: no breaking change without a major version or an approval;
- blocking: no sensitive value in clear text in the repository;
- warning: naming and style conventions;
- warning: documentation of error codes.
This baseline grows over time, from real incidents rather than theoretical standards.
The role that remains with people
Automating checks does not remove the need for human decisions. It moves them to where they have value: peer review of merge requests, arbitration of exceptions, evolution of the rule set. A committee can still have a role, but in evolving the rules, not in approving every API one by one.
What to take away
Effective API governance comes down to a small number of rules, checked by the pipeline, blocking when the stakes justify it, with an assumed exception process and a drift check in production. It is less spectacular than a complete reference framework, but it is applied at every deployment, with no silent exceptions. And it works on any gateway, because the rules bear on the contract and the intent, not on the product.
Alongside its consulting work, CAB Ingénierie develops STOA, a sovereign iPaaS and API integration platform.
Let's talk about your project
Has your API governance stayed on paper, or, on the contrary, is it slowing everyone down? Tell us about your context in a few lines: cab-ingenierie.com · contact@cab-ingenierie.com