architecture-descriptionestablished · medium operational burden

API Versioning

Also known as: versioning, api-evolution, backward-compatibility

Intent

Evolve APIs without breaking existing clients, using explicit versioning strategy.

Problem

API changes break clients. Clients can't all update simultaneously. Need controlled evolution.

Forces

•Consumers deploy on their own schedule
•Breaking changes inevitable (business, security, tech)
•Maintaining old versions has cost
•Discovery: how do clients know what versions exist?

Solution

✓ When to Use

•Public APIs with external consumers
•Multiple client teams (mobile, web, partners)
•Long-lived APIs with evolving requirements

✗ When Not to Use

•Internal APIs with coordinated deploys
•Single consumer (version in sync)
•GraphQL (field-level deprecation)

Pros

+Clients migrate on their schedule
+Safe evolution: old versions work
+Clear contract per version

Cons

−Maintenance burden: multiple versions running
−Code duplication or complex routing
−Documentation overhead
−Sunset pressure: clients delay migration

Cost Profile

Infrastructure

Low — routing logic

Operational

Medium — version lifecycle, monitoring

Cognitive

Low — standard practice

Failure Modes

Zombie versions: deprecated but heavily used
Version skew: client on v1, server only v3
Implicit versioning: clients break silently
Documentation drift: version docs outdated

Real-World Examples

Alternatives

graphql
never-break
consumer-driven-contracts

Related Patterns

consumer-driven-contracts
api-gateway
feature-flag
deprecation-policy

Competency Domains

distribution communicationeconomics evolutionreliability opsdeployment