Code-Memo

API Versioning

Why versioning is needed

1. Clients ship on their own schedules; breaking changes without versions strand old apps.
2. Versioning lets you deprecate fields and routes with a communicated timeline.
3. It reduces fear of shipping improvements when the contract is explicit.

URI versioning (/v1, /v2)

1. Put the major version in the path (/v1/users): easy to see in logs and docs.
2. Downside: proliferates URLs and caches; still the most common pattern for public REST.
3. Avoid silent changes inside /v1 once published; add /v2 for incompatible changes.

Header-based versioning

1. Clients send Accept: application/vnd.company.v2+json or API-Version: 2.
2. Keeps URLs stable; harder to grep logs unless you log the header.
3. Ensure intermediaries (CDNs, caches) vary on the version header when responses differ.

Backward compatibility strategies

1. Additive changes: new optional fields, new endpoints, new enum values with tolerant readers.
2. Deprecation headers (Deprecation, Sunset, links to migration guides).
3. Provide dual-write/dual-read windows and concrete sunset dates for removals.