Master Spring Boot 3 API Versioning: 5 Practical Strategies

Spring Boot 3 practical case collection now includes over 80 articles, and a PDF e‑book is available for subscribers.

1. Introduction

Maintaining multiple API versions in a system ensures compatibility and allows new features without breaking existing clients. Proper version naming, upgrade strategy, and deprecation planning are required.

2. Practical Cases

2.1 URL Path Versioning

Place the version number in the URL path and separate controllers into version‑specific packages.

Group controllers by version (e.g., v1 , v2 ).

Create controller classes in each package.

Define request mappings with @RequestMapping or @GetMapping , @PostMapping that include the version segment.

<code>package com.pack.version.way1.v1;

@RestController
@RequestMapping("/users/v1")
public class UserController {
    @GetMapping
    public User get() {
        return new User("v-1", 11);
    }
}
</code>

<code>package com.pack.version.way1.v2;

@RestController
@RequestMapping("/users/v2")
public class UserController {
    @GetMapping
    public User get() {
        return new User("v-2", 22);
    }
}
</code>

2.2 Request Parameter Versioning

Pass the version as a query parameter.

<code>@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping(params = "version=1")
    public User v1() {
        return new User("v-1", 11);
    }

    @GetMapping(params = "version=2")
    public User v2() {
        return new User("v-2", 11);
    }
}
</code>

2.3 Request Header Versioning

Specify the version in a custom HTTP header.

<code>@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping(headers = "x-api-v=1")
    public User v1() {
        return new User("v-1", 11);
    }

    @GetMapping(headers = "x-api-v=2")
    public User v2() {
        return new User("v-2", 11);
    }
}
</code>

2.4 Accept Header Versioning

Use the Accept header with custom media types.

<code>@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping(produces = "application/v1+json")
    public User v1() {
        return new User("v-1", 11);
    }

    @GetMapping(produces = "application/v2+json")
    public User v2() {
        return new User("v-2", 22);
    }
}
</code>

Clients set the Accept header to the desired version.

2.5 Custom Annotation Versioning

A more advanced approach uses a custom annotation to manage multiple versioned controllers; see the linked article for details.

Elegant! Custom annotation for multi‑version controller interfaces

These five methods cover the most common ways to implement API version control in Spring Boot.

For further reading, see Spring Boot REST API version control solutions and choices .