What is API Versioning?

Common schemes include versioning in the URL path (`/v1/users`, `/v2/users`), in a request header, or in the request payload itself. Whichever mechanism is used, the point is the same: a breaking change — renaming a field, changing a response shape, removing an endpoint — gets shipped as a new version rather than silently altering the behavior existing integrations depend on. Good versioning discipline draws a hard line between breaking and non-breaking changes: adding a new optional field is safe to ship into an existing version, but removing a field, changing its type, or altering required parameters is not — that needs a new version, with the old one supported for a defined deprecation window. Skipping this distinction is how a "minor update" quietly breaks every integration overnight. Versioning is also the mechanism that makes deprecation possible in a controlled way — without distinct versions, a provider has no way to retire an old behavior for some consumers while keeping it running for others still mid-migration.