API versioning is less about choosing a number and more about controlling change. This guide compares URL, query-parameter, header, and content-negotiation strategies, then provides a reusable checklist for introducing, documenting, testing, deprecating, and retiring an API version without surprising existing clients.
Overview
A breaking API change alters a client-visible contract. Renaming a field, changing its type, removing an endpoint, tightening validation, changing authentication requirements, or changing the meaning of a response can all require a versioning decision. The right approach depends on how clients discover the API, whether intermediaries inspect requests, how many consumers you support, and how much operational complexity your team can manage.
Versioning should be part of API design before the first breaking release. Define what counts as compatible, how long clients can remain on an old version, where migration guidance will live, and which team owns the retirement decision. For cloud-native corporate applications, also include gateways, observability, contract tests, SDKs, deployment pipelines, and access controls in the plan.
Versioning strategies compared
| Strategy | Example | Strengths | Trade-offs | Useful when |
|---|---|---|---|---|
| URL path | GET /v2/customers/42 | Visible in logs, documentation, browsers, and gateway rules; easy for clients to understand. | Creates distinct routes and can encourage duplicated handlers or schemas. | Public APIs, independently supported versions, and teams that value operational visibility. |
| Query parameter | GET /customers/42?version=2 | Simple to add without changing the path; easy to test manually. | May be omitted accidentally and can be inconsistently handled by caches, documentation, or routing rules. | Controlled internal APIs or transitional designs where explicit routing is still needed. |
| Header | API-Version: 2026-01-01 | Keeps resource URLs stable and supports date-based or capability-based contracts. | Less visible in copied links and browser tests; clients and gateways must set and preserve the header. | Managed APIs with disciplined client libraries, gateways, and request tooling. |
| Content negotiation | Accept: application/vnd.example.customer-v2+json | Uses HTTP representation semantics and separates resource identity from representation format. | More complex to explain, document, test, and troubleshoot across tools. | Organizations with mature HTTP practices and multiple representations of the same resource. |
There is no universal best method. URL versioning is often the clearest default for a public REST API because the selected contract is visible in requests and operational tooling. Header or content-negotiation approaches can work well when a platform already standardizes headers and client libraries. Query parameters are easy to introduce but deserve stricter validation so a missing or misspelled value does not silently select an unexpected contract.
Do not confuse versioning with deployment. A new application deployment can remain backward compatible and need no new API version. Conversely, two API versions may run from the same application build. Treat the public contract, not the release number, as the thing being versioned.
Checklist by scenario
When introducing a breaking capability
- Write down the exact incompatibilities and identify which clients, endpoints, fields, status codes, and authentication flows are affected.
- Choose one version-selection mechanism and apply it consistently across related resources.
- Define the compatibility boundary: what remains valid in the old version and what is deliberately different in the new one.
- Update the OpenAPI description, examples, schemas, error responses, authentication requirements, and changelog.
- Decide whether the new version will share implementation code with the old version or use separate handlers, serializers, and validation rules.
- Add contract tests for existing clients and new-version behavior before enabling traffic.
- Confirm that gateways, caches, rate limits, authorization rules, metrics, traces, and logs distinguish versions where necessary.
For a practical contract-testing workflow, pair this checklist with the OpenAPI contract testing workflow for cloud APIs. The goal is to detect an accidental contract change before it reaches a dependent application.
When onboarding a new client
- Record the client owner, environment, integration purpose, selected API version, and expected migration contact.
- Provide a minimal request and response example, including authentication, pagination, errors, idempotency, and retry behavior where relevant.
- Make version selection explicit in the quick-start code and test collection rather than relying on a default.
- Give the client a compatibility test suite or representative fixtures.
- Explain how deprecation notices will be communicated and where lifecycle dates will be published.
Keep secrets and credentials out of examples and repositories. API versioning does not replace sound authentication and configuration practices; review the related guidance on API keys, OAuth 2.0, and mTLS and enterprise secrets management.
When deprecating an old version
- Inventory active consumers using gateway logs, client registration records, support data, and version-specific metrics.
- Confirm that the replacement version covers every required use case, including error handling and less common endpoints.
- Publish a migration guide with before-and-after requests, response changes, field mappings, and testing steps.
- Set a review date and an intended retirement date, subject to contractual and operational constraints.
- Return clear deprecation information in documentation and, where appropriate, response headers such as
DeprecationorSunset. Verify that your gateway and client tooling preserve and display them correctly. - Monitor old-version traffic and contact owners whose usage remains active.
When retiring a version
- Verify that no approved clients, scheduled jobs, integrations, or undocumented internal tools still depend on it.
- Confirm that dashboards and alerts distinguish planned retirement from an unexpected outage.
- Remove routes, schemas, policies, tests, SDK methods, and documentation only after the retirement decision is approved.
- Return a deliberate response for retired calls, with a migration link where practical, instead of failing ambiguously.
- Record the decision, final traffic evidence, exceptions, and rollback plan.
What to double-check
Backward-compatibility checklist
Before calling a release compatible, review each item:
- Existing URLs, methods, required headers, authentication scopes, and content types still work.
- Existing response fields retain their meaning and data types.
- New response fields are safe for clients that reject unknown properties.
- Required request fields have not been added without a compatibility path.
- Enum values, nullability, numeric precision, date formats, pagination, sorting, and filtering behavior remain understood by existing clients.
- HTTP status codes and error-body shapes remain within the documented contract.
- Rate limits, timeouts, retry behavior, idempotency rules, and webhook payloads have been considered.
- Authorization changes do not accidentally remove access from valid existing use cases.
- Generated SDKs, API collections, mock servers, and examples match the deployed contract.
- Observability can separate old-version failures from new-version failures.
Use a JSON formatter or validator during payload review, but do not treat valid JSON as proof of compatibility. A response can be syntactically valid while changing a field's meaning or violating the documented schema. For debugging request failures, the HTTP status code troubleshooting reference can help separate routing, authentication, validation, and server errors.
Deprecation notice template
Subject: Planned retirement of [API version]
What is changing: We will retire [version and affected endpoints] because [brief reason].
Who is affected: Clients sending [version selector] or calling [routes].
Replacement: Migrate to [replacement version] using [migration guide URL].
Important differences: [field, behavior, authentication, or error changes].
Timeline: Deprecation begins on [date]; planned retirement review is [date].
Support: Contact [team or channel] with the client name, affected requests, and migration status.
Migration-plan template
- Inventory: List every client, owner, environment, endpoint, and version selector.
- Map: Create a field and behavior mapping from the old contract to the new one.
- Implement: Update the client, configuration, SDK, tests, and operational dashboards.
- Validate: Run contract, integration, negative, load, and authorization tests.
- Release safely: Use a controlled rollout and monitor version-specific errors and latency.
- Confirm: Obtain client-owner sign-off and record the production migration date.
- Close: Remove the old dependency and update the inventory.
Common mistakes
- Versioning every change. Additive, backward-compatible changes may not require a new version. Excessive versions increase testing and support work.
- Relying on an undocumented default. A missing version selector should produce a deliberate, documented result rather than silently changing behavior.
- Publishing a date without an owner. A retirement date needs a responsible team, usage evidence, exception process, and communication channel.
- Testing only the happy path. Validate malformed input, authorization failures, pagination boundaries, retries, timeouts, and unknown fields.
- Ignoring non-REST contracts. Webhooks, event payloads, SDKs, batch jobs, and asynchronous workflows need the same compatibility review. See the webhook debugging and reliability guide when a version change affects event delivery.
- Duplicating business logic without controls. Separate version handlers can drift. Keep shared domain behavior deliberate and test version-specific mapping at the boundary.
- Assuming documentation is migration support. A reference page is not enough; include examples, field mappings, known incompatibilities, and a runnable validation path.
When to revisit
Revisit your API versioning strategy before seasonal planning cycles, major client onboarding, authentication changes, gateway migrations, or any release that modifies a required field, response meaning, error contract, or authorization rule. Also review it when workflows or tools change: a new API gateway, OpenAPI generator, contract-testing framework, SDK pipeline, observability platform, or documentation system can alter how versions are selected, validated, and communicated.
At least twice a year, inspect version-specific traffic, unresolved migration exceptions, contract-test coverage, documentation examples, and retirement candidates. Refresh HTTP, OpenAPI, gateway, and documentation-tool examples after major framework releases or platform changes. A short review is usually enough:
- List active versions and their owners.
- Compare documented behavior with deployed behavior.
- Review breaking-change proposals against the compatibility checklist.
- Test deprecation headers, gateway routing, logs, and client visibility.
- Choose one action: keep, improve migration support, announce deprecation, or prepare retirement.
Use this article as a release-gate checklist: make the version decision explicit, test it against real client contracts, document the migration path, and keep evidence for the eventual retirement decision.