API versioning allows you to evolve your API over time without breaking existing clients. By introducing changes under a new version identifier, you give consumers time to migrate while keeping the old interface stable.
API versioning is the practice of managing changes to an API by assigning distinct identifiers to different iterations of its interface. When a breaking change is needed — such as renaming a field, changing a response structure, or removing an endpoint — a new version is published alongside the old one. This lets existing clients continue working without modification. Non-breaking changes, like adding optional fields, typically do not require a new version.
The most common strategy embeds the version directly in the URL path, for example /v1/users or /v2/orders. It is highly visible, easy to test in a browser, and simple to route at the infrastructure level. The main drawback is that it technically violates REST principles, since a resource's URL should ideally identify the resource, not its representation version. Despite this, it remains the most widely adopted approach due to its simplicity.
Header versioning passes the version in a custom HTTP request header such as Accept-Version: 2 or via the Accept header using media types like application/vnd.myapi.v2+json. This keeps URLs clean and aligns more closely with HTTP semantics. The downside is reduced discoverability — clients cannot simply paste a versioned URL into a browser — and it adds complexity to routing logic and caching configurations.
Another approach appends the version as a query parameter, for example /users?version=2. It is easy to implement and keeps the base URL stable, making it a low-friction option for simple or internal APIs. However, query parameters are often stripped by proxies and CDNs, and mixing versioning concerns into the query string can conflict with filtering or pagination parameters. It is generally considered the least robust strategy for public APIs.
Regardless of the versioning mechanism, following Semantic Versioning (MAJOR.MINOR.PATCH) helps communicate the scope of changes clearly. Breaking changes increment the major version, backward-compatible additions increment minor, and bug fixes increment patch. A clear deprecation policy — such as supporting old versions for at least 12 months after a new version ships — is critical for developer trust. Always communicate sunset dates through headers like Sunset and Deprecation in API responses.
Avoid versioning too granularly; versioning per resource rather than per endpoint reduces proliferation and confusion. Document all versions, even deprecated ones, until they are fully sunset. Implement version negotiation defensively: if no version is specified, either default to the latest stable version or return a 400 error with clear guidance rather than silently guessing. Finally, invest in automated contract testing tools like Pact or Dredd to catch breaking changes before they reach production.
© RM Full Stack & AI Engineer · All guides · Roadmaps · Open the app