API versioning strategies in HLD - System Design Guide

Problem Statement

When an API evolves, clients using older versions may break due to incompatible changes. Without a clear versioning strategy, it becomes impossible to maintain backward compatibility, causing service disruptions and forcing all clients to upgrade simultaneously.

Solution

API versioning strategies allow multiple versions of an API to coexist, enabling clients to choose which version to use. This is done by embedding version information in the URL path, request headers, or query parameters, so servers can route requests to the correct version implementation without breaking existing clients.

Architecture

Client v1

→API Gateway

↓

Client v2

→API Gateway

This diagram shows clients using different API versions routed through an API Gateway to the corresponding service version implementations.

Trade-offs

✓ Pros

→

Allows backward compatibility by supporting multiple API versions simultaneously.

→

Enables gradual client migration to newer API versions without service disruption.

→

Improves API lifecycle management by isolating changes to specific versions.

✗ Cons

→

Increases maintenance overhead as multiple API versions must be supported and tested.

→

Can cause confusion if versioning strategy is inconsistent or poorly documented.

→

May lead to code duplication or complexity in service implementations.

Use when your API undergoes breaking changes and you have multiple clients that cannot upgrade simultaneously, especially at scale above hundreds of clients.

Avoid if your API is stable with no breaking changes expected or if you control all clients and can enforce simultaneous upgrades.

Real World Examples

Amazon

Uses URL path versioning (e.g., /v1/, /v2/) to maintain backward compatibility for its AWS APIs while rolling out new features.

Stripe

Uses header-based versioning to allow clients to specify API version in request headers, enabling smooth upgrades without changing URLs.

GitHub

Supports media type versioning where clients specify API version in the Accept header, allowing flexible version negotiation.

Alternatives

No versioning

No explicit versioning; all clients use the same API endpoint and must adapt to changes immediately.

Use when: Only when you control all clients and can guarantee simultaneous updates without breaking changes.

Feature toggles

Use feature flags to enable or disable new API features without changing the API version.

Use when: When changes are additive and backward compatible, avoiding the need for multiple versions.

Summary

API versioning prevents client breakage by allowing multiple API versions to coexist.

Common strategies include URL path, headers, and query parameters to specify versions.

Choosing the right versioning approach depends on client control, scale, and change frequency.