What is API Versioning in Microservices?

API Versioning in Microservices is a technique used to manage changes in APIs without breaking existing client applications.

It allows multiple versions of the same API to coexist so that:

• Old clients continue working
• New features can be introduced safely
• Backward compatibility is maintained

API versioning is one of the most important practices in:

• Microservices Architecture
• Distributed Systems
• Cloud-Native Applications
• Enterprise APIs

Why API Versioning is Important

In Microservices:

• Services evolve continuously
• API contracts change over time
• Frontend and mobile applications depend on APIs

Without versioning:

• Existing clients may break
• Production failures may occur
• Application compatibility issues arise

API versioning ensures:

• Safe API evolution
• Backward compatibility
• Smooth client migration

Simple Banking Example

Suppose a banking application provides:

GET /accounts
    

Initial response:

{
  "accountNumber": "12345",
  "balance": 50000
}
    

Later business requirement changes:

• Add account type
• Add currency
• Modify response structure

Without versioning:

• Existing mobile apps may fail
• Frontend applications may break

With API versioning:

• Old clients continue using v1
• New clients migrate to v2

Without API Versioning

API Structure Changes
       |
Old Clients Break
       |
Production Issues
    

With API Versioning

Old Clients -> /v1/accounts

New Clients -> /v2/accounts
    

Both versions work independently.

How API Versioning Works

Client Sends Request
       |
Version Identified
       |
Correct API Version Invoked
       |
Response Returned
    

Main Goals of API Versioning

• Maintain backward compatibility
• Support gradual migration
• Enable safe API evolution
• Reduce breaking changes

Types of API Versioning

• URI Versioning
• Request Parameter Versioning
• Header Versioning
• Media Type Versioning

1. URI Versioning

Version number is included in API URL.

Example

/api/v1/accounts

/api/v2/accounts
    

Banking URI Versioning Example

Version 1

GET /api/v1/accounts
    

Response

{
  "balance": 50000
}
    

Version 2

GET /api/v2/accounts
    

Response

{
  "balance": 50000,
  "currency": "INR"
}
    

Advantages of URI Versioning

• Easy to understand
• Simple implementation
• Browser-friendly
• Most widely used approach

Disadvantages of URI Versioning

• Multiple URLs for same resource
• URL changes required

2. Request Parameter Versioning

Version is passed as query parameter.

Example

/accounts?version=1

/accounts?version=2
    

Banking Request Parameter Example

GET /transactions?version=2
    

Advantages

• Simple implementation
• No URL restructuring

Disadvantages

• Less RESTful
• Harder caching support

3. Header Versioning

Version information is sent using HTTP headers.

Example

API-VERSION: 1
    

Banking Header Version Example

GET /accounts

Headers:

API-VERSION: 2
    

Advantages

• Cleaner URLs
• More RESTful

Disadvantages

• Harder testing
• Less visible versioning

4. Media Type Versioning

Version is specified in:

Accept Header
    

Example

Accept:
application/vnd.bank.v1+json
    

Media Type Banking Example

GET /accounts

Accept:
application/vnd.bank.v2+json
    

Advantages

• Highly RESTful
• Flexible API evolution

Disadvantages

• Complex implementation
• Harder debugging

Most Commonly Used Versioning Strategy

In real-world enterprise applications:

URI Versioning
    

is most commonly used because:

• Simple
• Easy to understand
• Developer-friendly

Real Banking Scenario

Version 1 API:

GET /api/v1/payments
    

supports:

• Domestic payments only

Version 2 API:

GET /api/v2/payments
    

adds:

• International payments
• Multi-currency support
• Fraud scoring

Old clients continue using v1 safely.

API Deprecation

Older API versions eventually become:

Deprecated
    

Clients receive migration notice.

Banking API Deprecation Example

v1 Supported Until:
31-Dec-2026
    

Clients are asked to migrate to:

v2
    

Versioning in Microservices Architecture

In Microservices:

• Each service may evolve independently
• Different versions may coexist

API versioning helps avoid:

• Breaking distributed communication

API Gateway with Versioning

API Gateway commonly routes requests based on API version.

API Gateway Example

/api/v1/payments -> Payment Service V1

/api/v2/payments -> Payment Service V2
    

Spring Boot URI Versioning Example

@RestController

@RequestMapping("/api/v1/accounts")

public class AccountControllerV1 {

}
    

Spring Boot Version 2 Example

@RestController

@RequestMapping("/api/v2/accounts")

public class AccountControllerV2 {

}
    

Header Versioning Example in Spring Boot

@GetMapping(

    value = "/accounts",

    headers = "API-VERSION=1"

)
    

Benefits of API Versioning

• Backward compatibility
• Safe API evolution
• Reduced production failures
• Supports gradual client migration
• Improves maintainability
• Enhances developer experience

Real Banking Use Cases

• Payment APIs
• Transaction APIs
• ATM integrations
• Mobile banking APIs
• Fraud detection APIs
• Third-party banking integrations

E-Commerce Example

Version 1:

Order API without coupon support
    

Version 2:

Order API with discount coupons
    

Old mobile apps continue working without issues.

Challenges of API Versioning

• Maintaining multiple versions
• Increased testing complexity
• Higher maintenance cost
• Version synchronization challenges

Problem with Too Many Versions

Suppose:

v1
v2
v3
v4
v5
    

Maintaining all versions becomes difficult.

Best Practices for API Versioning

• Use versioning from beginning
• Prefer backward-compatible changes
• Document APIs clearly
• Deprecate versions gradually
• Use semantic versioning where possible
• Maintain proper API contracts

API Versioning vs No Versioning

Professional Interview Answer

API Versioning in Microservices is a technique used to manage API changes without breaking existing client applications. It allows multiple versions of APIs to coexist so that older clients continue functioning while newer features are introduced safely. Common API versioning strategies include URI versioning, header versioning, request parameter versioning, and media type versioning. API versioning helps maintain backward compatibility, supports gradual migration, and enables safe API evolution in banking systems, cloud-native applications, and enterprise microservices architectures.

Summary

API Versioning is one of the most important practices used in modern Microservices and Distributed Systems.

It enables APIs to evolve safely while maintaining compatibility with existing clients and reducing production risks.

Banking systems, payment gateways, e-commerce platforms, cloud-native applications, and enterprise distributed systems heavily rely on API versioning for stable and scalable integrations.

Understanding API versioning is essential for backend developers, API architects, cloud engineers, and microservices developers building scalable distributed applications.