How to Version API in Spring Boot: Simple Guide

In Spring Boot, you can version your API by including the version in the URI path, request parameters, or HTTP headers. The most common way is to add the version number in the URL path like /api/v1/resource. This helps clients use different API versions without breaking existing integrations.

Syntax

API versioning in Spring Boot can be done mainly in three ways:

• URI Path Versioning: Add version in the URL path, e.g., /api/v1/resource.
• Request Parameter Versioning: Use a query parameter like ?version=1.
• Header Versioning: Use a custom HTTP header like X-API-VERSION: 1.

Each method requires mapping the controller or method to handle the version accordingly.

java

@RestController
@RequestMapping("/api/v1")
public class MyController {

    @GetMapping("/resource")
    public String getV1() {
        return "Response from API version 1";
    }
}

// For request param versioning
@RestController
@RequestMapping("/api/resource")
public class MyController {

    @GetMapping(params = "version=1")
    public String getV1() {
        return "Response from API version 1";
    }
}

// For header versioning
@RestController
@RequestMapping("/api/resource")
public class MyController {

    @GetMapping
    public String getV1(@RequestHeader(value = "X-API-VERSION", required = false) String version) {
        if ("1".equals(version)) {
            return "Response from API version 1";
        }
        return "Default response";
    }
}

Example

This example shows how to version an API using URI path versioning in Spring Boot. Two versions of the same resource are exposed under different paths.

java

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VersionedApiController {

    @GetMapping("/api/v1/greeting")
    public String greetingV1() {
        return "Hello from API version 1";
    }

    @GetMapping("/api/v2/greeting")
    public String greetingV2() {
        return "Hello from API version 2 with new features";
    }
}

Output

GET /api/v1/greeting -> "Hello from API version 1"
GET /api/v2/greeting -> "Hello from API version 2 with new features"

Common Pitfalls

Common mistakes when versioning APIs in Spring Boot include:

• Mixing versioning methods without clear rules, causing confusion.
• Not updating documentation to reflect version changes.
• Using only header versioning without fallback, which can break clients that don't send headers.
• Hardcoding version strings in many places instead of centralizing them.

Always keep versioning consistent and communicate changes clearly.

java

// Wrong: Mixing URI and header versioning without clear separation
@RestController
@RequestMapping("/api/resource")
public class ConfusedController {

    @GetMapping("/v1")
    public String getV1() {
        return "v1 response";
    }

    @GetMapping
    public String getDefault(@RequestHeader(value = "X-API-VERSION", required = false) String version) {
        if ("2".equals(version)) {
            return "v2 response";
        }
        return "default response";
    }
}

// Right: Use one versioning strategy per endpoint
@RestController
public class ClearVersionController {

    @GetMapping("/api/v1/resource")
    public String getV1() {
        return "v1 response";
    }

    @GetMapping("/api/v2/resource")
    public String getV2() {
        return "v2 response";
    }
}

Quick Reference

Summary tips for API versioning in Spring Boot:

• Use URI path versioning for clear and visible API versions.
• Request parameter versioning is easy but less common.
• Header versioning is flexible but requires clients to send headers.
• Keep versioning consistent across your API.
• Document each version clearly for your users.

Key Takeaways

Version your API by including the version in the URI path, request parameters, or headers in Spring Boot.

URI path versioning is the most common and easiest to manage and understand.

Avoid mixing versioning strategies without clear rules to prevent confusion.

Always update your API documentation to reflect version changes.

Centralize version strings to simplify maintenance and updates.