REST API Versioning in Spring Boot: Four Implementation Methods

In many real‑world projects, managing API versions becomes essential to avoid breaking existing clients when the service evolves. This article introduces the need for RESTful API versioning and demonstrates four practical approaches using a simple Spring Boot Maven project.

The first example shows a StudentV1 response returning a single name field, followed by a second version StudentV2 that splits the name into firstName and lastName . These two data models illustrate why versioning is required as requirements diverge.

Four versioning techniques are covered:

URI Versioning

@RestController
public class StudentUriController {

    @GetMapping("v1/student")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping("v2/student")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}

Requests to http://localhost:8080/v1/student and http://localhost:8080/v2/student return the respective JSON payloads.

Request‑Parameter Versioning

@RestController
public class StudentParmController {

    @GetMapping(value="/student/param", params = "version=1")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/param", params = "version=2")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}

Clients specify the version with a query parameter, e.g., http://localhost:8080/student/param?version=1 .

Custom Header Versioning

@RestController
public class StudentHeaderController {

    @GetMapping(value="/student/header", headers = "X-API-VERSION=1")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/header", headers = "X-API-VERSION=2")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}

Clients send the version in the X-API-VERSION header; Postman screenshots illustrate the requests.

Media‑Type (Accept Header) Versioning

@RestController
public class StudentProduceController {

    @GetMapping(value="/student/produce", produces = "application/api-v1+json")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/produce", produces = "application/api-v2+json")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}

The client selects the version via the Accept header, e.g., application/api-v1+json or application/api-v2+json .

When choosing a versioning strategy, consider factors such as URI pollution, misuse of request headers, caching implications, ease of direct browser testing, and documentation clarity. No single method fits all scenarios; the decision should be based on project requirements.

The article also lists major API providers and the versioning approaches they adopt: GitHub uses media‑type versioning, Microsoft prefers custom headers, Twitter/Baidu/Zhihu use URI paths, and Amazon relies on request‑parameter versioning.

Overall, the guide provides a hands‑on comparison of four REST API versioning techniques in Spring Boot, helping developers select the most suitable approach for their services.