Versioning Protocols

Versioning Protocols are the conventions API and software teams use to communicate change: how a new release is numbered, how a breaking change is signaled, and how a consumer knows whether an upgrade is safe. The best known is Semantic Versioning (SemVer) — the MAJOR.MINOR.PATCH scheme where each position carries a specific promise about compatibility — but the same discipline shows up in URL path versions, media-type versions, and header-based negotiation across the API landscape.

• Semantic Versioning (SemVer) - MAJOR.MINOR.PATCH numbers where a bump in each slot tells the consumer exactly what changed and whether it breaks them.
• Where the version lives - In the path (/v2/), in a custom or Accept header, or in a query parameter — each with tradeoffs for caching, routing, and discoverability.
• Breaking vs. non-breaking change - The core distinction every protocol exists to make legible, so additive changes don’t force a version and destructive ones don’t happen silently.
• Deprecation and sunset - Pairing a new version with a clear timeline for retiring the old one, increasingly via Deprecation and Sunset HTTP headers.

In practice, versioning is where API governance meets human deadlines — teams reach for a new version when a change would break consumers, and I’ve written often about how much of real-world versioning is a coping mechanism rather than a clean protocol. Consistent versioning is one of the clearest signals of a mature API operation, it’s directly checkable in an OpenAPI definition, and it matters more than ever in the agentic turn, when automated consumers need a machine-readable way to know a contract has changed before they break against it.