Versioning & Governance

Once an API has consumers you do not control, every change is a negotiation. Governance is what keeps that from becoming either paralysis or breakage.

Prefer evolution to versioning. Additive change costs nothing: new optional fields, new endpoints, new enum values that old clients can ignore. A surprising share of "we need v2" is really a handful of additive changes plus a rename someone wanted. Every version you publish is a version you maintain.

When you must version, the two common approaches are a URL segment (/v2/orders) and a header or media type. URL versioning is blunt, obvious, trivially cacheable, and easy to route — which is why most public APIs use it despite purists disliking it. Header versioning keeps URLs stable and is harder to debug by hand.

Deprecation is a process, not an announcement. Publish a policy with a real timeline, signal it in the response — Deprecation and Sunset headers exist for this — instrument which consumers are still calling the old path, and contact them directly. Turning something off because the date passed, without checking who is still on it, is how you cause an incident on purpose.

Know what you have. An inventory of every API, its version, its owner, and its consumers is the precondition for everything else. Teams that cannot answer "who calls this?" cannot safely change anything, so they stop changing things, and the estate ossifies.

Consistency is a feature. A style guide covering naming, pagination, error shapes, filtering, and date formats means a developer who has used one of your APIs can predict the next. Enforce it by linting the spec in CI, not by review comments — automated rules are applied evenly and do not depend on who reviewed it.