API versioning strategies in HLD - System Design Exercise

Design: API Versioning System

Design focuses on versioning strategies for RESTful APIs including version identification, routing, and deprecation. Authentication, business logic, and database design are out of scope.

Functional Requirements

FR1: Support multiple versions of the API simultaneously

FR2: Allow clients to specify which API version to use

FR3: Ensure backward compatibility for older clients

FR4: Enable smooth transition and deprecation of old versions

FR5: Provide clear error messages for unsupported versions

Non-Functional Requirements

NFR1: Handle up to 10,000 concurrent API requests

NFR2: API response latency p99 under 300ms

NFR3: Availability of 99.9% uptime

NFR4: Minimal disruption during version upgrades

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

Key Components

API Gateway or Router for directing requests based on version

Versioned Controllers or Handlers in the backend

Documentation system indicating supported versions

Monitoring and logging for version usage

Deprecation notification mechanism

Design Patterns

URI Path Versioning

Request Header Versioning

Query Parameter Versioning

Content Negotiation (Accept Header)

Backward Compatibility and Deprecation Patterns

Reference Architecture

Client
  |
  |--(1) Specify version via URL path /v1/resource or /v2/resource
  |--(2) Specify version via custom header X-API-Version
  |--(3) Specify version via query param ?version=1
  |
API Gateway / Router
  |
  |-- Routes request to appropriate versioned backend service
  |
Backend Services
  |-- v1 Service
  |-- v2 Service
  |
Documentation & Monitoring
  |
Deprecation Notification System

Components

API Gateway / Router

Nginx, Kong, or AWS API Gateway

Route incoming requests to the correct API version based on versioning strategy

Versioned Backend Services

RESTful services implemented in Node.js, Java, or Python

Handle business logic for each API version separately to maintain backward compatibility

Documentation System

Swagger / OpenAPI

Provide clear API version documentation and usage guidelines

Monitoring and Logging

Prometheus, Grafana, ELK Stack

Track usage metrics and errors per API version

Deprecation Notification System

Email alerts, API response headers

Inform clients about deprecated versions and timelines

Request Flow

1. Client sends API request specifying version via URL path, header, or query parameter.

2. API Gateway inspects the request to identify the version.

3. Gateway routes the request to the corresponding versioned backend service.

4. Backend service processes the request and returns response.

5. If version is deprecated, response includes warning headers.

6. Monitoring system logs request and version usage.

7. Documentation is updated to reflect supported versions.

Database Schema

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

Scaling Discussion

Bottlenecks

API Gateway routing becoming a single point of failure under high load

Increased maintenance overhead with multiple active API versions

Client confusion due to multiple versioning methods

Data inconsistency if backend services diverge in behavior

Solutions

Use load-balanced and redundant API Gateways to handle traffic

Implement automated testing and CI/CD pipelines for each version

Standardize on a single versioning method and phase out others

Maintain shared core logic libraries to reduce divergence

Interview Tips

Time: Spend 10 minutes understanding versioning requirements and constraints, 20 minutes designing versioning strategies and components, 10 minutes discussing scaling and trade-offs, 5 minutes summarizing.

Explain different versioning strategies and their pros/cons

Discuss how clients specify versions and how routing works

Highlight importance of backward compatibility and deprecation

Address scaling challenges and operational concerns

Show awareness of developer experience and documentation