What is API Versioning?

API versioning is the practice of releasing API changes without forcing every existing client to update at the same moment. A mobile app may remain on an older release; an accounting integration may not support new fields immediately. A version strategy makes that transition controlled.

How Does It Work?

The most common approach is to include the version in the URL, such as /v1/orders and /v2/orders. Some systems carry the version in a header or media type. Small backward-compatible additions may not need a new version, but renamed fields, changed response shapes, or business-rule changes usually require a clear version plan.

Versioning is not only a URL convention. Deprecation dates, migration guides, sample requests, error codes, and changelogs are part of the same process.

Business Use

In banking, ERP, e-commerce, and mobile app APIs, not every integrating customer can upgrade at the same speed. That is why REST API design should plan backward compatibility, documentation, and version lifetime together. OpenAPI schemas make differences between versions visible and can support automated tests.

Good versioning does not mean keeping old versions alive forever; it gives clients a measurable and safe migration window.