Back to roadmap
Module 5 · APIs & Application LayerDay 04225 min

API Versioning Strategies

How to evolve a contract without breaking clients.

← PreviousNext →
Day 042

API Versioning Strategies

Client v1
client
Client v2
client
API gateway
edge
/v1
service
/v2
service
Signal path
Dual-run during migration
Client v1
client
flow
API gateway
edge
Client v2
client
flow
API gateway
edge
API gateway
edge
flow
/v1
service
Memory hook

API Versioning Strategies: how to evolve a contract without breaking clients

Mental model

turn boundaries into contracts

Design lens

Maintaining many versions is costly — keep two at most.

Recall anchors
SchemesCompatDeprecation

Why it matters

Public APIs need versioning so clients can rely on a contract. Common schemes: URL path (/v1), Accept header (application/vnd.acme+json; version=1), or content negotiation. Each has tradeoffs.

Deep dive

URL versioning is the most discoverable and the most common.

Header versioning keeps URLs stable but requires client cooperation.

Backward-compatible changes (additive) shouldn't bump version. Breaking (rename, remove, semantic change) must.

Plan deprecation: announce, dual-run, sunset, remove. Months, not days.

Demo / scenario

Adding a required field 'currency' to /orders.

  1. v1 has no currency; v2 adds it.
  2. v1 endpoint defaults currency to USD on the server.
  3. Both run side by side; partners migrate over 6 months.
  4. v1 sunset announced and removed at deadline.

Tradeoffs

  • Maintaining many versions is costly — keep two at most.
  • Schema validation must understand both shapes.
  • Deprecation discipline matters more than scheme.

Diagram

Client v1
Client v2
API gateway
/v1
/v2
Dual-run during migration.

Mind map

Check yourself

Loading quiz…

Sources & further reading

← PreviousNext →