What is versioning in REST? What are the ways that we can use to implement versioning?

Question

Accepted Answer

REST API Versioning is a technique used to manage changes in an API without breaking existing client applications. As APIs evolve, new features, request formats, or response structures may be introduced. Versioning allows multiple API versions to coexist so that existing consumers can continue using older versions while newer clients adopt the latest version.

Key Points:
• API versioning helps maintain backward compatibility.
• It allows APIs to evolve without disrupting existing consumers.
• Multiple versions can run simultaneously.
• Clients can migrate to newer versions at their own pace.
• Versioning is essential for public APIs and large-scale enterprise applications.

Why Do We Need API Versioning?

Consider an API:

GET /employees

Version 1 Response:

{
  "id": 101,
  "name": "John"
}

Later, a new requirement adds email information.

Version 2 Response:

{
  "id": 101,
  "name": "John",
  "email": "john@example.com"
}

Without versioning:

• Existing clients may break.
• Mobile applications may fail.
• Third-party integrations may stop working.

Versioning solves this problem by allowing both versions to remain available.

Common API Versioning Approaches

1. URI Versioning (Most Common)

The version number is included in the URL path.

Example:

GET /api/v1/employees

GET /api/v2/employees

Advantages:

• Simple and easy to understand.
• Easy to test and document.
• Widely used in enterprise applications.

Spring Boot Example:

```
@GetMapping("/api/v1/employees")
public List getEmployeesV1() {

return employeeService.getEmployees();
}
```
2. Request Parameter Versioning

The version is passed as a query parameter.

Example:

GET /employees?version=1

GET /employees?version=2

Advantages:

• URL structure remains unchanged.
• Easy to implement.

Disadvantages:

• Less commonly used.
• Version information is less visible.

Spring Boot Example:

@GetMapping(
    value = "/employees",
    params = "version=1"
```
)
public String getEmployeesV1() {

return "Version 1";
}
```
3. Custom Header Versioning

The client specifies the API version using a custom HTTP header.

Example:

GET /employees

Header:

X-API-VERSION: 1

Advantages:

• Clean URLs.
• Versioning separated from resource identifiers.

Disadvantages:

• Harder to test directly in browsers.
• Less visible to API consumers.

Spring Boot Example:

@GetMapping(
    value = "/employees",
    headers = "X-API-VERSION=1"
```
)
public String getEmployeesV1() {

return "Version 1";
}
```
4. Media Type (Content Negotiation) Versioning

The API version is specified in the Accept header.

Example:

GET /employees

Header:

Accept: application/vnd.company.v1+json

or

Accept: application/vnd.company.v2+json

Advantages:

• Considered highly RESTful.
• Keeps URLs unchanged.

Disadvantages:

• More complex implementation.
• Harder for beginners to understand.

Spring Boot Example:

@GetMapping(
    value = "/employees",
    produces =
```
    "application/vnd.company.v1+json"
)
public Employee getEmployeeV1() {

return employee;
}
```
Comparison of Versioning Approaches

URI Versioning

• Easy to implement
• Highly popular
• Easy documentation

Request Parameter Versioning

• Simple
• Less commonly used

Custom Header Versioning

• Clean URLs
• Requires custom headers

Media Type Versioning

• RESTful approach
• More complex

Example:
Suppose an e-commerce application exposes:

Version 1:

GET /api/v1/products

Returns:

Product Name
Price

Version 2:

GET /api/v2/products

Returns:

Product Name
```
Price
Category
Rating
```
Older mobile applications continue using v1 while newer applications consume v2.

This ensures smooth upgrades without service disruption.

Best Practice

For most enterprise applications and interviews:

URI Versioning

Example:

/api/v1/employees

/api/v2/employees

is the most commonly preferred approach because it is simple, explicit, and easy to maintain.

Real-World Example

Popular companies use API versioning extensively:

• Payment APIs
• Banking APIs
• E-commerce APIs
• Social Media APIs

This allows them to introduce new features without breaking existing integrations.

Interview Tip:
A concise interview answer is:

"REST API versioning is a strategy used to manage API changes while maintaining backward compatibility for existing clients. Common versioning approaches include URI versioning (/api/v1/resource), request parameter versioning (?version=1), custom header versioning (X-API-VERSION), and media type versioning using the Accept header. Among these, URI versioning is the most widely used due to its simplicity and clarity."