How do you introduce API governance to a team?

In three steps and in this order. Run the rules and tell nobody, so you learn what your estate actually looks like. Then turn them on as advisory findings and work the backlog down with the teams. Only then promote the small number of rules you would genuinely revert a release for, which is usually a handful rather than a category.

What do you do about the violations an existing API already has?

Treat them as an agenda rather than a debt. Sort the first run into things you want fixed, things you want noted and things you now know to switch off, which takes a couple of hours and calibrates the guide against reality. New APIs then start from the calibrated standard, and the existing ones work through their list at a pace somebody agreed to.

Should new and existing APIs follow the same API standards?

The same standard with different enforcement. A new API can meet a rule at no cost, while an existing one may need a breaking change to do the same thing. Blocking both identically punishes the API that is already carrying consumers. A per-project override lets one service depart from one rule while the standard stays where it is for everybody else.

Who approves exceptions to API design standards?

Whoever owns the standard, and the important part is that the decision is recorded rather than negotiated in a pull request. An exception should name the project and the rule, carry a reason somebody can evaluate later, and leave the rest of the guide applying to that project. An exception nobody can find is indistinguishable from the rule being ignored.

Rolling Governance Out Without Stopping the Team

Switch a complete style guide on over APIs that already exist and the first run returns a number nobody wants to see. That number is not a problem. What you do in the following hour is.

Measure first, and tell nobody

The first run is research, and treating it as a status report is the fastest way to lose the room.

Run the rules over the APIs you already ship, with everything advisory and nothing blocking, and read the output yourself. You will find three groups. There will be violations you genuinely want fixed, violations worth noting and never chasing, and rules that turned out not to describe how your organisation actually builds APIs.

The same guide, three arrangements, and only one of them survives contact with a team. Measuring costs nobody anything and tells you what your estate looks like. Warning creates a backlog somebody can work. Blocking at the end applies to the handful of rules the first two steps proved were worth it.

Sorting that list once takes a couple of hours, and it produces a guide calibrated against your APIs instead of against a template. The third group is the valuable one, because a rule you switch off deliberately costs nothing while a rule you leave on trains everybody to ignore findings.

Then warn, and work the backlog

The second step is where governance becomes visible, and the tone of that introduction matters more than the contents.

Turn the guide on as advisory findings, and say plainly that nothing is blocking. Give the teams the list for their own APIs rather than a league table, because the first is a task and the second is a judgement. Expect the count to fall quickly at first, since a large share of the initial number is usually two or three rules firing everywhere.

Watch the trend rather than the level. A count going down means the arrangement is working, and a count that only grows means everything is advisory in practice and the guide has become a report.

Then block, and only for a handful

The last step is the one people want to do first, and it works only because the other two came before it.

Promote a rule to blocking when you would revert a release for it. That usually means rules whose violation breaks something downstream, such as duplicate operation identifiers or two paths that resolve to the same route, plus the few security rules where shipping is worse than stopping. Severity and enforcement covers how to choose them.

Announce the promotion before it takes effect, and make sure the violations of that rule are already at zero. A blocking rule introduced onto a non-empty backlog stops work on its first day, which is the precise outcome the whole sequence was designed to avoid.

New APIs and existing APIs are different populations

Applying one enforcement level to both is the most common way a sensible guide becomes unpopular.

A new API can satisfy a naming rule at no cost, because nothing has been published yet. An API with three years of consumers may need a breaking change to satisfy the same rule, which is a disproportionate price for tidiness. Treating both identically punishes the API that is actually carrying load.

The mechanism for this is a cascade rather than two guides. The organisation holds one standard, and a project departs from it where it has to, visibly and with the rest of the guide still applying. Two separate standards drift apart within a year, while one standard with recorded exceptions stays one standard.

Who grants an exception and how long it lasts

An exception is governance working, provided somebody can find it later.

Keep the authority with whoever owns the standard, so exceptions stay comparable. Require a reason that names what applying the rule would cost, since a reason nobody can evaluate is a preference with paperwork. Review them on some cadence, because the legacy service that could not be renamed in March may be retired by October.

The test of a healthy scheme is that you can list your exceptions. An organisation that cannot does not have a standard, it has a default that some teams follow.

The order nobody should use

For completeness, the sequence that fails. Enable every rule at error severity on the day the guide is announced.

Within a week, one of two things has happened. Either work has stopped, and the guide is switched off under pressure and never comes back. Or teams have found the route around the check, and the guide is now a formality that costs everybody time and changes nothing.

Both outcomes are difficult to reverse, because the second attempt has to overcome the memory of the first.

In Routebase

The three steps map onto three settings, and none of them requires a migration.

The guide runs continuously once it is enabled, so the measuring step is the default state. Enforcement on publish is a separate switch that stays off until you turn it on, which is what makes step one and step two the same configuration with different expectations.

Severity is set at the organisation and overridden per project, and the project view shows a source column reading custom, org or default with a one-click reset. An exception is therefore visible rather than folded into the numbers. A rule changed from its shipped default carries an override badge for the same reason.

The alerts cover the part a rules table cannot. Thresholds for quality score and documentation coverage come with a live preview of how many specifications fall below them. Alerts fire on breaking changes, and on drafts left untouched beyond a window that defaults to a month. Configuring any of this needs the governance permission held by admins and owners. The Style Guide and API Design Settings guides cover the settings themselves.