Backend
API Versioning
Evolving an API over time without breaking existing clients — via the URL (/v2), headers or content negotiation, together with clear deprecation windows. It lets you ship change while old integrations keep working. The real cost is maintaining several versions at once, so prefer additive, backward-compatible changes and reserve new versions for genuinely breaking ones.
Purpose
API versioning lets you evolve an API — change payloads, rename fields, alter behaviour — without breaking the clients already depending on it. It exists to reconcile a provider's need to change with consumers' need for stability.
When to Use It
Any API with external or independently-deployed consumers you cannot update in lockstep — public APIs, mobile apps in the wild, partner integrations.
Internal APIs where you control every caller often skip formal versions and simply coordinate deploys.
Trade-offs
Explicit versions give stability but multiply the surface you must maintain and test. The cheaper path — only ever making additive, backward-compatible changes — avoids versions but constrains how you can evolve. Never break a published contract silently.
Implementation
Version in the URL (/v2/…) for visibility, or via a header or media type for cleanliness. Prefer additive changes (new optional fields) so old clients keep working; when a breaking change is unavoidable, ship a new version, announce a deprecation window, and watch usage of the old one before retiring it.