API governance is an architecture problem, not a developer problem
Most organisations discover they have an API governance problem the same way they discover they have a tech debt problem: when the cost of the accumulated decisions becomes visible. By that point, the API landscape has hundreds of endpoints, inconsistent authentication patterns, no common contract standards, and documentation that is either missing or wrong.
API governance is consistently treated as a developer concern. Teams adopt standards, API gateways get deployed, documentation tools get purchased. None of these solve the underlying problem because the underlying problem is an architecture decision that was never made.
The decision that was never made
In most organisations, APIs grew organically. Each team chose its own patterns. Microservices proliferated. Integrations were built point-to-point. Nobody made a binding decision about what an API in this organisation looks like, how it is versioned, how it is authenticated, and how it is retired.
That missing decision is the governance gap. The gateway and the tooling are downstream of it.
What API governance actually requires
Effective API governance requires four things at the architecture level: a canonical API design standard with mandatory and advisory elements; a centralised registry that is authoritative rather than aspirational; a lifecycle model that includes deprecation and retirement; and accountability for the API portfolio at an architectural level, not just at the team level.
The registry problem
Most organisations have an API registry. Most API registries are incomplete, outdated, or both. A registry that developers update voluntarily will always drift from reality. The registry needs to be the source of truth for deployment: if an API is not in the registry, it cannot be promoted to production. That is the only enforcement mechanism that reliably works.
Versioning and deprecation are not optional
API versioning that is never enforced creates the same problems as no versioning. Consumers build on v1, v1 is updated without a version increment, consumers break. Or v1 is never retired, and the organisation carries twenty versions of the same API indefinitely. Deprecation policy needs teeth: a mandatory notice period, a breaking change protocol, and a retirement date that is enforced.
