microversions

Microversions are a method of API versioning that allows small, incremental changes to an API without breaking existing clients. Each microversion represents a minor addition, modification, or deprecation within the same API family, designed to be backward compatible with earlier microversions.

In a microversioned API, a service maintains a range of supported microversions. New features and changes are introduced in newer microversions, while older clients can continue to operate using their previously negotiated version. Clients specify the desired microversion for a request, typically via a header or query parameter, and servers respond using that version if it is within the supported range. If the requested microversion is not available, the server may return an error or negotiate to the closest compatible version.

Microversions enable gradual feature rollout and deprecation planning. They help preserve client stability by avoiding breaking changes and reduce the need for large, disruptive releases. At the same time, they impose some complexity: servers must support multiple code paths for different microversions, and clients must maintain awareness of which features are available at each version.

Commonly associated with large-scale REST APIs, microversions are used by ecosystems that require long-lived clients and frequent feature evolution. OpenAPI and other API design practices can be extended with microversions to manage compatibility over time. Overall, microversions aim to balance rapid API evolution with predictable client behavior, trading some implementation complexity for smoother interoperability.