Spring Boot API Versioning

Version only when a published contract must break while old clients keep working. Most internal APIs never need a version, and every version is a promise to maintain two contracts.

When to use

• Deciding whether a service needs versions at all, and which strategy to adopt.
• Implementing version routing with path segments, headers, media types, or Spring API versioning.
• Classifying a proposed change as additive or breaking.
• Adding deprecation and sunset signaling to a version or an endpoint.
• Planning client migration, the overlap window, and the removal of a retired version.

When not to use

• Endpoint design, statuses, and the error body: use spring-boot-rest-api.
• DTO field evolution mechanics and over-posting control: use spring-boot-dto.
• Version rendering in the generated document: use spring-boot-openapi.
• Request mapping, filters, and interceptors: use spring-boot-mvc.
• Identity, scopes, and authorization: use spring-boot-security.