API versioning for services in Microservices - System Design Exercise

Design: API Versioning for Microservices

Design focuses on API versioning strategies and integration with microservices. Does not cover internal microservice business logic or database design.

Functional Requirements

FR1: Support multiple API versions simultaneously to avoid breaking existing clients

FR2: Allow clients to specify which API version they want to use

FR3: Enable smooth transition and deprecation of old API versions

FR4: Ensure backward compatibility for critical services

FR5: Provide clear documentation and discoverability of available API versions

Non-Functional Requirements

NFR1: Handle up to 10,000 concurrent API requests with versioning

NFR2: API response latency p99 under 200ms including version negotiation

NFR3: 99.9% uptime for all API endpoints

NFR4: Minimal impact on existing microservices architecture

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

Key Components

API Gateway or Reverse Proxy

Microservices with versioned endpoints

Version negotiation logic

Documentation service or portal

Monitoring and logging for version usage

Design Patterns

URI versioning (e.g., /v1/resource)

Header versioning (e.g., Accept header)

Query parameter versioning

Backward compatibility and graceful deprecation

Canary releases and blue-green deployments for new versions

Reference Architecture

Client
  |
  |---> API Gateway (handles version routing)
          |
          |---> Microservice v1 (handles /v1/* requests)
          |
          |---> Microservice v2 (handles /v2/* requests)
          |
          |---> Documentation Service

Components

API Gateway

Kong / NGINX / Envoy

Route requests to correct microservice version based on version info in URL or headers

Microservice v1

Any microservice framework (e.g., Spring Boot, Node.js)

Serve API version 1 endpoints

Microservice v2

Same as v1 but updated for version 2

Serve API version 2 endpoints with new features or fixes

Documentation Service

Swagger / OpenAPI / Redoc

Provide discoverability and details of all supported API versions

Monitoring & Logging

Prometheus / ELK Stack

Track usage and errors per API version for operational insights

Request Flow

1. Client sends API request with version info in URL path (e.g., /v1/resource) or header (e.g., Accept: application/vnd.example.v1+json).

2. API Gateway inspects the version info and routes the request to the corresponding microservice version.

3. Microservice processes the request and returns response in the expected format for that version.

4. API Gateway forwards the response back to the client.

5. Documentation service provides clients with information about available API versions and their endpoints.

6. Monitoring collects metrics on API version usage and errors.

Database Schema

Not applicable as versioning is handled at API and service routing level, not at database schema level.

Scaling Discussion

Bottlenecks

API Gateway becomes a single point of failure or bottleneck under high load

Maintaining multiple versions increases deployment and operational complexity

Increased resource usage due to running multiple service versions simultaneously

Client confusion if versioning strategy is inconsistent or poorly documented

Solutions

Use a highly available and horizontally scalable API Gateway cluster

Automate deployment pipelines to manage multiple versions efficiently

Implement shared code and backward compatibility to reduce duplicated effort

Provide clear versioning guidelines and comprehensive documentation

Use feature flags and canary deployments to gradually roll out new versions

Interview Tips

Time: Spend 10 minutes understanding versioning requirements and constraints, 20 minutes designing versioning strategy and architecture, 10 minutes discussing scaling and operational concerns, 5 minutes summarizing.

Explain different versioning strategies and trade-offs

Emphasize importance of backward compatibility and smooth client experience

Describe role of API Gateway in routing and version negotiation

Discuss how to handle deprecation and client communication

Highlight monitoring and documentation as key operational aspects

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