API versioning is the discipline of changing a public API over time without breaking the clients that already depend on it. Once an API is published and integrated by outside developers, its request and response shapes become a contract; removing a field, renaming a parameter, or changing a default can break running software that the API provider does not control. Versioning gives providers a structured way to introduce incompatible changes while letting existing clients continue to call a stable, older behavior.
Several strategies exist, each with trade-offs. URI versioning places a version number in the path, such as a segment like v1 or v2, making the version explicit and easy to route. Header-based versioning carries the requested version in an HTTP header or in the Accept media type, keeping resource URLs stable at the cost of being less visible. Query-parameter versioning passes the version as a parameter. Many APIs also distinguish breaking from non-breaking changes using ideas borrowed from semantic versioning, reserving a new major version only for changes that are not backward compatible.
Stripe’s API offers a well-documented example of a date-based approach. Stripe pins each account to a specific API version identified by a date, and as its documentation explains, it ships major releases that may include “non-backward-compatible changes” alongside monthly releases that contain “only backward-compatible changes” and are safe to adopt. New SDK versions are pinned to the API version current at their release, while a per-request header can override the account default, allowing a single integration to upgrade gradually and test new behavior before committing to it.
A crucial companion to versioning is a deprecation policy. Providers announce that an older version or a specific field will be removed, mark it as deprecated in the documentation and often in response metadata, and give clients a defined window to migrate before support ends. Clear definitions of what counts as a backward-compatible change, like Stripe’s published list of additive changes that clients must tolerate, let providers improve an API continuously without forcing every consumer to update in lockstep.
Done well, API versioning lets an interface evolve for years while preserving trust with the developers who build on it. The choice of strategy shapes the developer experience: explicit URI versions are simple but multiply endpoints, header and date-based schemes keep URLs clean but demand careful documentation, and in GraphQL many teams avoid versioned endpoints entirely by adding new fields and deprecating old ones within a single evolving schema. Whatever the mechanism, the goal is the same, to change the contract safely while honoring the one that clients already rely on.