API Versioning in Spring

1. Introduction

APIs are the foundation of digital communication in today’s fast-paced software ecosystem. APIs unavoidably change as applications do. However, how can we address problems or add new features without upsetting current customers?

API versioning is the solution. Recently, native support for API versioning was added to Spring Framework and Spring Boot, making the process easier than before.

In this tutorial, we’ll discuss API versioning in Spring.

2. Why API Versioning Matters and Best Practices?

APIs unavoidably change as applications do, whether it’s by adding new features, changing response formats, or resolving inconsistencies.

For current clients who depend on older contracts, these modifications may create breaking points. By guaranteeing backward compatibility while permitting innovation, API versioning offers an organized method of managing this evolution.

It lowers adoption barriers, allows customers to upgrade at their own speed, and preserves service evolution transparency.

2.1. Best Practices

We need to apply versioning only when it is truly required, avoiding unnecessary complexity that can burden both developers and clients. Any changes introduced should be clearly documented so that consumers of the API are aware of what is new and what has been deprecated.

It is equally important to provide migration paths and timelines, ensuring that deprecations are handled gracefully rather than abruptly. Automated testing should be in place to guarantee that all supported versions continue to function as expected.

Ultimately, the chosen versioning strategy must align with business needs and organizational priorities, striking the right balance between innovation and stability.

3. How Can We Use API Versioning in Spring Boot?

Let’s explore how to implement common API versioning strategies in Spring Boot using Java (17+) and Spring Boot (3.x or 4.x).

3.1. URI Versioning (Path-Based)

This method makes the versioning scheme clear and simple to comprehend by adding version numbers directly into the URL path.

Developers can keep distinct controllers for each version, and clients can easily see which version they are calling. Although this approach is popular and straightforward, it can clutter endpoints and is occasionally regarded as less RESTful.

Here’s how we can implement URI versioning in Spring Boot:

@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller {
    @GetMapping
    public String getUsersV1() {
       return "User list from API v1";
    }
}
@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller {
    @GetMapping
    public String getUsersV2() {
        return "User list from API v2 with extra fields";
    }
}

3.2. Request Parameter Versioning

Request Parameter Versioning allows clients to use a query parameter in the request to specify the API version. This method is easy to use and keeps the base endpoint the same across all versions.

However, it requires clients to remember to include the parameter, and if omitted, the server must handle defaults or fallbacks gracefully.

The following example demonstrates request parameter versioning:

@RestController
public class UserParamController {
    @GetMapping("/api/users")
    public Object getUsers(@RequestParam(name = "version", defaultValue = "1") String version) {
        if ("1".equals(version)) {
            return List.of("Alice", "Bob");
        } else if ("2".equals(version)) {
            return List.of(
              new UserV2("Alice", "[email protected]", 30),
              new UserV2("Bob", "[email protected]", 25)
            );
        }
        return "Unsupported API version";
    }
}

3.3. Header Versioning

Header Versioning uses custom request headers to indicate which version of the API the client wants to consume. This approach keeps URLs tidy and keeps endpoint design and versioning issues apart.

The trade‑off is that clients must be aware of and correctly set the header, which can add complexity to integration. The following example demonstrates header versioning:

@RestController
public class UserHeaderController {
    @GetMapping(value = "/api/users", headers = "X-API-VERSION=1")
    public List<UserV1&gt; getUsersV1() {
        return List.of(
          new UserV1("Alice"),
          new UserV1("Bob")
        );
    }

    @GetMapping(value = "/api/users", headers = "X-API-VERSION=2")
    public List<UserV2> getUsersV2() {
        return List.of(
          new UserV2("Alice", "[email protected]", 30),
          new UserV2("Bob", "[email protected]", 25)
        );
    }
}

3.4. Content Negotiation

Content Negotiation leverages the Accept header with custom media types to determine which version of the API should be returned.

This approach is flexible and aligns well with RESTful principles, as it allows multiple representations of the same resource. The downside is that it requires careful setup and agreement on MIME types, which can be more complex for teams to manage.

Here’s how we can implement Content Negotiation:

@RestController
@RequestMapping("/api/users")
public class UserContentNegotiationController {
    @GetMapping(produces = "application/vnd.company.v1+json")
    public String getUsersV1() {
        return "User list v1";
    }

    @GetMapping(produces = "application/vnd.company.v2+json")
    public String getUsersV2() {
        return "User list v2";
    }
}

3.5. Using Spring Boot Native Versioning Support

Spring Framework 7 and Spring Boot 4 introduce native support for API versioning through annotations, reducing the need for custom solutions.

By directly integrating versioning into controller definitions, this standardized approach enhances consistency across projects and streamlines maintenance.

It also enhances developer experience by integrating seamlessly with existing request mapping and content negotiation mechanisms. Here’s how we can implement native versioning support in Spring Boot:

@RestController
public class UserMimeController {
    public static final String V1_MEDIA = "application/vnd.example.users-v1+json";
    public static final String V2_MEDIA = "application/vnd.example.users-v2+json";

    @GetMapping(value = "/api/users", produces = V1_MEDIA)
    public List<UserV1> usersV1() {
        return List.of(
          new UserV1("Alice"), 
          new UserV1("Bob")
        );
    }

    @GetMapping(value = "/api/users", produces = V2_MEDIA)
    public List<UserV2> usersV2() {
        return List.of(
          new UserV2("Alice", "[email protected]", 30),
          new UserV2("Bob", "[email protected]", 25)
        );
    }

    // Optional fallback
    @GetMapping(value = "/api/users", produces = MediaType.APPLICATION_JSON_VALUE)
    public List<UserV1> defaultUsers() {
        return List.of(
          new UserV1("Alice"), 
          new UserV1("Bob")
        );
    }
}

4. What’s New in Spring Framework 7 & Boot 4

The most recent iterations of Spring offer first-rate API versioning support, such as versioning controllers and endpoints that have native annotations. Furthermore, reduced inconsistencies by standardizing patterns among teams.

In addition, enhanced developer experience with integrated tools improved compatibility with request mapping and content negotiation in Spring.

When compared to custom solutions, the native support for API versioning through annotations offered by Spring Framework 7 and Spring Boot 4 significantly streamlines the process.

Instead of manually handling version checks in controllers, we can now declare versions directly at the method level using the @ApiVersion annotation. This approach improves readability, reduces boilerplate, and ensures consistency across teams.

Here’s an illustration of how to use native annotations to define two versions of the same endpoint:

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping
    @ApiVersion("1")
    public List usersV1() {
        return List.of(
          new UserV1("Alice"), 
          new UserV1("Bob")
        );
    }

    @GetMapping
    @ApiVersion("2")
    public List usersV2() {
        return List.of(
          new UserV2("Alice", "[email protected]", 30),
          new UserV2("Bob", "[email protected]", 25)
        );
    }
}

The above features eliminate the need for developers to use custom versioning solutions. Alternatively, we can rely on Spring’s standardized methodology, which guarantees uniformity throughout projects.

5. Common API Versioning Strategies in Spring

The following table elaborates on the common API versioning strategies in Spring:

6. Conclusion

In this article, we discussed how API versioning is a strategic approach that strikes a balance between stability and advancement rather than merely being a technical safety measure.

We can easily manage API evolution with the help of Spring Framework 7 and Spring Boot 4. Spring now offers a unified, standardized approach to versioning, regardless of whether we choose URI-based, header-based, or content negotiation.

Spring’s API versioning is moving from custom solutions to native, first-class support, making our APIs client-friendly and future-proof.

With Spring Boot 4’s native support, we can now have a standardized, annotation-driven approach that improves consistency.

The tested code is available over on GitHub