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