Managing API Versions at Ten‑Million QPS: From Single Version to Coexisting Multi‑Versions

What No Version Means

In the early stage of a service, having no explicit version is the most rational choice because all callers are co‑located and can be upgraded together. Introducing version numbers at that point would add maintenance cost without any benefit.

The premise of a version‑less system is that every caller can be synchronously upgraded. When that premise breaks—because callers become external partners, legacy systems, or millions of mobile apps—the risk of an incompatible change skyrockets.

Cost of an Incompatible Change

Changes are divided into two categories:

Compatible changes : adding optional fields, new endpoints, or relaxing validation. Existing callers are unaffected.

Incompatible changes : deleting or renaming fields, tightening validation, or altering default behavior. Old callers may misinterpret data or fail silently.

The most dangerous are silent data‑corrupting changes, e.g., changing a monetary field from cents to yuan, which makes old callers produce amounts 100× larger without raising an error.

In a ten‑million‑QPS system, a small incompatible change can trigger a feedback loop: a few failures cause retries, which amplify traffic, increase load, generate more failures, and quickly snowball into an avalanche within seconds.

Compatible Design: Avoid New Versions When Possible

The first principle is to use compatible design to absorb changes, opening a new version only as a last resort.

Key practices:

Never delete or modify existing fields; add new fields instead. Deprecate old fields in documentation but keep them in the schema.

Make new fields optional and provide sensible default values.

Define a tolerant handling rule for unknown fields: callers should ignore them rather than error out. This embodies the robustness principle—conservative sending, liberal receiving.

When a change cannot be handled compatibly (e.g., removing an authentication method or fundamentally changing a core field’s semantics), a new version becomes necessary.

Where to Put the Version

Three common placement options are compared:

URL path, e.g., /v1/order and /v2/order. Simple and visible but couples version to the address.

Custom request header, e.g., Api-Version. Keeps URLs clean and enables flexible negotiation, but version information is hidden and routing/configuration become more complex.

Protocol‑level metadata (e.g., RPC framework version tag). Transparent to business code but ties the design to a specific framework.

No option is universally optimal; external APIs usually prefer URL paths, while large internal RPC systems favor protocol‑level embedding.

Special caution: if version is part of the cache key, uncontrolled version proliferation can dramatically reduce cache hit rates and increase memory pressure.

Multi‑Version Coexistence

After a version is introduced, the challenge is to run multiple versions simultaneously without interference.

Two coexistence strategies:

Physical isolation : Deploy each version in separate clusters. Guarantees isolation but incurs high resource cost.

Logical coexistence : Handle different versions within the same service instance using branching logic (e.g., if version == v1). Saves resources but adds code complexity and risk of cross‑version bugs.

In massive QPS scenarios, a hybrid approach is common: keep the active main version physically isolated for stability, while legacy tail versions are handled logically to reduce cost, and aggressively push them toward retirement.

Version Governance: Prevent Version Explosion

Without governance, a system can become a “version cemetery” where many versions linger, each with a few stubborn callers, making the overall system hard to understand and maintain.

A clear lifecycle with defined stages is essential:

Active : Recommended version, receives new features.

Maintained : Stable previous version, only bug fixes.

Deprecated : Marked as obsolete, still usable with warnings.

Sunset : Fixed decommission date, callers are notified.

Retired : Fully removed, requests are rejected.

Effective governance relies on four practical levers:

Observability: monitor version‑level traffic to know who is still using which version.

De‑gradation incentives: add latency or warning headers to deprecated versions to motivate migration.

Hard sunset dates: publish concrete decommission timelines.

Pre‑release review: require a justification that a change cannot be handled compatibly before opening a new version.

Evolution Path from No Version to Converged Multi‑Version

The article outlines a progression:

At 10⁴ QPS , a version‑less system with compatible design is cheapest.

At 10⁵–10⁶ QPS , external callers force the introduction of versions, but most changes are still absorbed by compatible design.

At 10⁷ QPS , version management shifts focus from “how to create versions” to “how to govern them”: observability, lifecycle rules, sunset mechanisms, and careful interaction with caching, rate‑limiting, and gray‑release controls become the true defensive moat.

The opening incident—renaming a field that broke a three‑year‑old reconciliation job—was not a human mistake but a lack of constraints on incompatible changes. The ultimate goal of version management is to maintain a predictable contract with all callers while the system evolves.