APIversioning

API versioning is the practice of managing changes to an application programming interface (API) so that clients can evolve without disruption. A version identifier is introduced and associated with a release, enabling different clients to rely on different API shapes.

Versioning can be achieved in several ways: URL path versioning, header versioning, query parameter versioning, and media type versioning through content negotiation. Each approach has trade-offs in discoverability, caching, and simplicity. URL versioning makes versions explicit in endpoints; header versioning keeps URLs clean; query parameters can complicate caching; media type versioning aligns with negotiation but requires client updates.

Lifecycle and compatibility: Semantic versioning is commonly used to convey the level of change. A major version indicates breaking changes, a minor version adds functionality in a backward-compatible way, and a patch provides backward-compatible bug fixes. Deprecation policies require ongoing support for older versions for a defined period, with migration guides and sunset timelines.

Governance and practice: Teams should define versioning rules, provide release notes, offer tooling for routing to the correct version, and monitor usage. Avoid surprise changes to existing versions; prefer additive changes to preserve compatibility.

Standards and interoperability: Documentation standards such as OpenAPI can help describe the versioned API surface and its lifecycle, aiding client development and governance.