REST API Versioning

As your API evolves, you may need to make changes that are not backward compatible. API versioning allows you to introduce new features without breaking existing clients.

There are several ways to version REST APIs:

1. URI Path Versioning (Most Common)

@RestController
public class UserControllerV1 {
    @GetMapping("/v1/users")
    public List getUsersV1() { ... }
}

@RestController
public class UserControllerV2 {
    @GetMapping("/v2/users")
    public List getUsersV2() { ... }
}

URL: /v1/users and /v2/users

2. Request Parameter Versioning

@GetMapping(value = "/users", params = "version=1")
public List getUsersV1() { ... }

@GetMapping(value = "/users", params = "version=2")
public List getUsersV2() { ... }

URL: /users?version=1 and /users?version=2

3. Header Versioning (Custom Header)

@GetMapping(value = "/users", headers = "X-API-Version=1")
public List getUsersV1() { ... }

@GetMapping(value = "/users", headers = "X-API-Version=2")
public List getUsersV2() { ... }

Request header: X-API-Version: 1

4. Content Negotiation (Accept Header)

@GetMapping(value = "/users", produces = "application/vnd.company.app-v1+json")
public List getUsersV1() { ... }

@GetMapping(value = "/users", produces = "application/vnd.company.app-v2+json")
public List getUsersV2() { ... }

Request header: Accept: application/vnd.company.app-v1+json

Which one to choose?

URI Path – Simple, visible, widely used (e.g., Twitter, Facebook).
Parameter – Easy to test in browser, but clutters URL.
Header – Clean URLs, but harder to test.
Accept Header – Most RESTful, follows HTTP standards, but complex.

Here is a complete example using URI versioning with different models:

// Version 1 - Simple user
public class UserV1 {
    private String name;
    private String email;
    // getters, setters
}

// Version 2 - User with address and phone
public class UserV2 {
    private String fullName;
    private String email;
    private String address;
    private String phone;
    // getters, setters
}

@RestController
public class UserVersioningController {
    
    @GetMapping("/v1/users")
    public List getUsersV1() {
        return Arrays.asList(
            new UserV1("John Doe", "john@example.com")
        );
    }
    
    @GetMapping("/v2/users")
    public List getUsersV2() {
        return Arrays.asList(
            new UserV2("John Doe", "john@example.com", "123 Main St", "555-1234")
        );
    }
}

Two Minute Drill

API versioning allows you to evolve your API without breaking existing clients.
URI path versioning (/v1/resource) is most common and simple.
Parameter versioning (?version=1) is easy but clutters URLs.
Header versioning keeps URLs clean but harder to test.
Accept header versioning is most RESTful but complex.
Choose what works best for your use case.

Practice Exercises Interview Questions Take Quiz

Need more clarification?

Drop us an email at career@quipoinfotech.com

Welcome to Quipoin

Quipoin Menu

REST API Versioning

Need more clarification?