On this page
When you need it, and when you do not
One team with one API does not need governance; it needs a good code review. Nordic APIs makes the same point: a small organisation with a single API that rarely changes probably does not need it. The need starts when the producer and the consumer of an API are different teams with different backlogs. Then a change that is routine for one team is an incident for another, and nobody is in the room for both.
- Signs you are there: a breaking change was found by the consumer in production; nobody can say who owns an endpoint; a retirement has been “planned” for a year because nobody knows who still calls it.
- Signs you are not: one team owns and calls every API, or all consumers are external customers behind a gateway with their own keys.
Three rules to write down first
| Rule | What it says | What keeps it true |
|---|---|---|
| Ownership | Every service, and so every endpoint, has one owner team; an endpoint may have its own owner where another team really owns it | An owner field in the spec or the catalog, a code owners file for the spec, and a regular report of gaps |
| Change policy | Which changes are breaking, what a breaking change needs before it merges, and how an endpoint is retired | A breaking-change check on every pull request, and the policy linked from the pull request template |
| Notification | The teams that consume an endpoint hear about a breaking change before it ships, in a channel they read | A per-endpoint list of consumer teams, kept by those teams, and alerts sent from it |
Ownership
Owners are teams, not people: people move, a team has a channel. Set the owner per service and override it on an endpoint only where another team really owns it. Make the owner visible where the work happens: in the spec, in the catalog, and in the repository, so a change to the spec asks the owner for review. On GitHub, a CODEOWNERS file in .github/, the root or docs/ requests review from the owners automatically, and a branch protection rule can require their approval.
# .github/CODEOWNERS
/services/orders/openapi.yaml @example-org/orders-team
/services/billing/openapi.yaml @example-org/billing-teamThen look for the gaps on a schedule. An owner field that points at a team that was dissolved is worse than an empty one. See orphaned API endpoints for a weekly routine.
Change policy
Write down what counts as breaking, because teams disagree at the edges: is a new enum value in a response breaking? Then say what each kind of change needs.
| Change | Example | What the policy asks |
|---|---|---|
| Additive | A new optional response field, a new endpoint | Ship it. No notice needed |
| Breaking | A removed field, a new required parameter, a narrowed type | Notice to the consumer teams before the merge, with a date and what to change; a reviewer from the owner team |
| Removal | Retiring an endpoint | The retirement checklist: consumers found, notice given, traffic at zero |
A breaking-change check on every pull request makes the policy visible at the moment it matters. OpenAPI breaking changes lists what tools such as oasdiff flag, and running an OpenAPI diff in CI shows the setup. Whether the check fails the build or only comments is a policy choice: a hard failure needs a documented way to accept an intended break.
Notification
This is the rule most governance programmes leave vague: “communicate breaking changes” in a guideline does not say to whom. The producer cannot keep the list; it does not see new callers. The consumer teams can: each one records the endpoints it calls, and the producer reads that list when a change comes. A notice then goes only to those teams, in their own channel. API breaking change alerts covers how to route it, and the API dependency map covers how the list is built.
Where Graphwake fits
Graphwake covers the ownership and notification rules, from your OpenAPI specs and the teams’ own subscriptions. Its CI step reports on every pull request and never blocks a build, so it fits next to whatever checks you already run.
Alerts only to consumer teams
Each team subscribes to the endpoints it calls. A breaking change alerts only those teams, in Slack, Microsoft Teams or email, before the merge when the spec comes through the CI step.
Optional ownership, weekly gaps
A service may have an owner team and an endpoint its own. Every Monday, admins get one email listing orphan endpoints, endpoints without an owner and services without an owner.
An impact score per change
Each change set gets a 0-100 score with public rules: breaking changes, affected teams, people to notify, and blind spots where nobody subscribes.
The same map in the editor
With Graphwake MCP on Pro and Enterprise, your AI assistant can ask who owns and who consumes an endpoint. See the MCP how-to.
What else teams add, and what each one catches
| Practice | Catches | Does not catch |
|---|---|---|
| Style guide with a linter (Spectral) | Inconsistent names, missing operation ids, missing owner fields, in every pull request | Whether a change breaks a caller, or who calls it |
| Breaking-change check (oasdiff) | A breaking change in the spec, before the merge | Which teams the change reaches |
| Design review | Bad shapes before they ship, and reuse across teams | Changes to existing endpoints that skip the review |
| Catalog (Backstage, Apigee API hub, Azure API Center) | What exists and who owns it | Per-endpoint consumers, when entries are kept by hand and drift |
| Gateway policies (Kong, Apigee) | Authentication, rate limits and per-key traffic at runtime | Internal calls that bypass the gateway; changes before they deploy |
| Consumer subscriptions and alerts | The teams to tell about a breaking change, per endpoint | Callers that never subscribed, until someone finds them |
A linter is the cheapest place to make ownership checkable. Spectral’s spectral:oas ruleset ships with OpenAPI rules; a few lines raise the ones you care about to errors and add your own, such as an owner field on every spec:
extends: ["spectral:oas"]
rules:
info-contact: error
operation-operationId: error
info-x-owner:
description: Every spec names the team that owns it.
given: "$.info"
severity: error
then:
field: x-owner
function: truthy 2:6 error info-contact Info object must have "contact" object. info
2:6 error info-x-owner Every spec names the team that owns it. info
7:9 error operation-operationId Operation must have "operationId". paths./orders.getspectral lint exits with a failure code on errors by default (--fail-severity sets the level), so one ruleset can fail a CI job or only report, as your policy says.
Rolling it out
Write the three rules on one page
Ownership, change policy, notification. Link it from the pull request template of every repository with a spec.
Collect the specs
One OpenAPI spec per service, in the repository or at a published URL. Governance you cannot check against a spec stays a wiki page.
Name owners
Per service first, per endpoint only where it differs. Leave unknowns empty and visible rather than guessed.
Map consumers
Ask each team to record the endpoints it calls, starting with the services that change most. Find which teams use an endpoint helps with the ones nobody knows.
Add the checks
A linter and a breaking-change check on every pull request that touches a spec. Start in report-only mode and raise to errors once the existing warnings are fixed.
Review the gaps every week
Unowned services, endpoints nobody consumes, breaking changes that shipped without a notice. Fix the list, not the people.
When a linter, catalog or gateway alone is enough
- Your problem is consistency, not breakage. A style guide enforced by a linter such as Spectral fixes naming, pagination and error shapes across teams.
- You need one inventory of everything with owners. A catalog such as Backstage covers services, libraries and resources as well as APIs.
- Your consumers are external customers. A gateway gives every caller a key and shows per-key traffic; a public changelog fits that audience.
Questions
What is API governance?
The rules a company keeps about how its APIs are designed, owned and changed, and the checks that keep those rules true: linters, breaking-change checks, reviews, catalogs and runtime policies.
At what size does a company need API governance?
When the teams that produce and consume an API are different teams, usually from about twenty engineers in several teams. A single team with a single API needs code review, not governance.
Who should own API governance?
A small group with members from the teams that build and call the APIs, often led by a platform team. Ownership of each API stays with the team that builds it.
Is a linter like Spectral enough?
For consistency, often yes. A linter checks the shape of each spec; it cannot tell whether a change breaks a caller or which team calls an endpoint. Add a breaking-change check and a consumer list for those.
How do I stop breaking changes from surprising other teams?
Write a change policy, check every spec change for breaking changes in the pull request, and have consumer teams subscribe to the endpoints they call so a breaking change reaches them before it merges.
Pick an endpoint. See who it reaches. 7-day free trial. Cancel before day 7 and you pay nothing.
Start free trialSources and last verified
- nordicapis.com/10-signs-you-might-need-api-governance/
- github.com/stoplightio/spectral
- raw.githubusercontent.com/stoplightio/spectral/develop/docs/reference/openapi-rules.md
- raw.githubusercontent.com/stoplightio/spectral/develop/docs/guides/2-cli.md
- docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
- backstage.io/docs/features/software-catalog/descriptor-format/
Sources checked on 2026-11-09.