API Versioning (Boot 4 / Framework 7)

API Versioning (Boot 4 / Framework 7)

Spring Framework 7 provides API versioning in the mapping layer. Prefer it over hand-rolled /v1 prefixes, custom HandlerMapping implementations, or version-sniffing filters.

Declare versions on mappings

@RestController
@RequestMapping("/api/orders")
class OrderController {

    @GetMapping(path = "/{id}", version = "1.0")
    OrderV1 getV1(@PathVariable UUID id) { ... }

    @GetMapping(path = "/{id}", version = "1.2")
    OrderV2 getV2(@PathVariable UUID id) { ... }
}

Use semantic version strings. A + suffix means the mapping handles that version and newer versions, for example version = "1.2+".

Configure one request resolution strategy

@Configuration
class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer
            .useRequestHeader("API-Version")
            .setDefaultVersion("1.0")
            .addSupportedVersions("1.0", "1.2");
    }
}

Choose exactly one source: request header, query parameter, path segment, or media-type parameter. Keep the choice consistent across the application. WebFlux uses the corresponding