API versioning for services in Microservices - System Design Guide

Problem Statement

When a service evolves, changing its API without versioning breaks existing clients. This causes failures and forces all clients to upgrade simultaneously, leading to downtime and poor user experience.

Solution

API versioning allows multiple versions of an API to coexist. Clients specify which version they use, so new changes do not break old clients. This enables gradual upgrades and backward compatibility.

Architecture

Client v1

→API Gateway

↓

Client v2

→API Gateway

This diagram shows clients calling different API versions routed by an API Gateway to corresponding service versions.

Trade-offs

✓ Pros

→

Enables backward compatibility for existing clients while evolving APIs.

→

Allows gradual client migration to newer API versions.

→

Reduces risk of breaking changes causing system-wide failures.

→

Supports parallel development and deployment of multiple API versions.

✗ Cons

→

Increases maintenance overhead for supporting multiple API versions.

→

Requires careful documentation and communication to clients.

→

Can lead to code duplication or complexity in service implementations.

When your service API changes frequently and you have multiple clients that cannot upgrade simultaneously, typically at scale of hundreds or more clients.

When your API is stable with rare changes or you control all clients and can coordinate simultaneous upgrades.

Real World Examples

Amazon

Uses API versioning to allow different versions of its product advertising API to coexist, enabling third-party developers to migrate at their own pace.

Twitter

Maintains multiple API versions to support legacy apps while rolling out new features in newer API versions.

Stripe

Implements API versioning to ensure payment integrations remain stable even as new API features are introduced.

Code Example

The before code breaks clients when the response format changes. The after code uses URL path versioning to keep old and new APIs separate, allowing clients to choose which version to call.

Microservices

### Before (No versioning, breaking change)
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/user')
def get_user():
    # Returns user name as string
    return 'Alice'

### After (With versioning via URL path)
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/v1/user')
def get_user_v1():
    # Old API returns name string
    return 'Alice'

@app.route('/v2/user')
def get_user_v2():
    # New API returns JSON object
    return jsonify({'name': 'Alice', 'id': 123})

Alternatives

Backward Compatibility Only

Instead of versioning, the API is designed to never break old clients by only adding non-breaking changes.

Use when: When API changes are minimal and can be guaranteed backward compatible without versioning.

Feature Flags

Use feature flags to toggle new API behaviors instead of separate versions.

Use when: When changes are small and can be controlled internally without exposing multiple API versions.

Summary

API versioning prevents breaking existing clients when APIs evolve.

It enables multiple API versions to coexist and clients to migrate gradually.

Versioning requires trade-offs in maintenance but improves system stability and client experience.

Practice

1. What is the main purpose of API versioning in microservices?

easy

A. To increase server hardware requirements

B. To improve database performance

C. To reduce network latency

D. To allow changes without breaking existing clients

Solution

1. Step 1: Understand API versioning goal

   API versioning is used to manage changes in APIs so that old clients still work without errors.

2. Step 2: Identify the main benefit

   This helps avoid breaking existing users when new features or fixes are added.

3. Final Answer:

   To allow changes without breaking existing clients -> Option D

4. Quick Check:

   API versioning = avoid breaking changes [OK]

Hint: API versioning prevents breaking old clients [OK]

Common Mistakes:

• Thinking it improves database speed
• Confusing it with network optimization
• Assuming it increases hardware needs

2. Which of the following is a common way to specify API version in a request?

easy

A. Using the URL path like /v1/resource

B. Embedding version in the database schema

C. Changing the server IP address

D. Using client-side cookies only

Solution

1. Step 1: Identify common API versioning methods

   API versions are often specified in the URL path, headers, or query parameters.

2. Step 2: Match the correct method

   Using the URL path like /v1/resource is a widely used and clear approach.

3. Final Answer:

   Using the URL path like /v1/resource -> Option A

4. Quick Check:

   URL path versioning = Using the URL path like /v1/resource [OK]

Hint: Version in URL path is common and clear [OK]

Common Mistakes:

• Confusing version with database schema
• Thinking server IP changes version
• Assuming cookies control API version

3. Given a microservice with two API versions running side by side, what happens when a client sends a request to /api/v2/users?

medium

A. The service processes the request using version 1 logic

B. The service returns an error because version 2 is unsupported

C. The service processes the request using version 2 logic

D. The service ignores the version and uses the latest version

Solution

1. Step 1: Understand version routing

   When multiple API versions run side by side, the version in the URL directs which logic to use.

2. Step 2: Match URL version to service logic

   A request to /api/v2/users should be handled by version 2 logic, not version 1 or latest by default.

3. Final Answer:

   The service processes the request using version 2 logic -> Option C

4. Quick Check:

   URL version directs logic = The service processes the request using version 2 logic [OK]

Hint: URL version selects matching service logic [OK]

Common Mistakes:

• Assuming version 1 logic runs always
• Thinking unsupported versions cause errors
• Believing latest version is default without version

4. A developer tries to version an API by changing the request header to X-API-Version: 3, but clients still get version 1 responses. What is the likely issue?

medium

A. The client is sending the wrong URL path

B. The service does not support header-based versioning

C. The server is down

D. The database schema is outdated

Solution

1. Step 1: Analyze versioning method mismatch

   If clients send version info in headers but the service expects URL path versioning, the header is ignored.

2. Step 2: Identify the cause of version mismatch

   The service likely does not support header-based versioning, so it defaults to version 1 responses.

3. Final Answer:

   The service does not support header-based versioning -> Option B

4. Quick Check:

   Unsupported header versioning = The service does not support header-based versioning [OK]

Hint: Check if service supports header versioning [OK]

Common Mistakes:

• Blaming wrong URL when header is used
• Assuming server down causes version mismatch
• Confusing database schema with API version

5. You need to design a microservice API that supports smooth migration from version 1 to version 2 without downtime. Which approach best supports this?

hard

A. Run both versions side by side and route requests based on URL version

B. Replace version 1 completely with version 2 immediately

C. Use only query parameters for versioning and ignore URL paths

D. Deploy version 2 on a different server without routing

Solution

1. Step 1: Understand smooth migration needs

   Smooth migration requires both versions to run simultaneously so clients can switch gradually.

2. Step 2: Choose routing strategy

   Routing requests based on URL version allows clients to specify which version they want, enabling coexistence.

3. Step 3: Evaluate other options

   Replacing immediately causes downtime; query-only versioning is less clear; separate servers without routing complicate access.

4. Final Answer:

   Run both versions side by side and route requests based on URL version -> Option A

5. Quick Check:

   Side-by-side versioning = Run both versions side by side and route requests based on URL version [OK]

Hint: Run versions side by side for smooth migration [OK]

Common Mistakes:

• Replacing old version immediately causing downtime
• Ignoring URL path versioning clarity
• Deploying without routing causing access issues