API Versioning Strategies: A Consumer Migration and Sunset Plan
Migrate API consumers with a version-selection matrix, a paginated-response example, Deprecation and Sunset headers, compatibility tests and retirement gates.
Treat a breaking change as a consumer migration
A new API version creates a place for incompatible behavior. It does not move consumers there. A workable migration also needs an inventory of affected clients, a tested replacement, a support policy, evidence of adoption and a controlled retirement decision.
Preserve the current version-selection mechanism if it still fits the system. Changing both the contract and how clients select it adds migration work. For a new API, choose a mechanism that the actual clients, caches and gateways can handle consistently.
This guide focuses on moving consumers through a breaking change. The companion API design for longevity guide covers the underlying contract, retry and pagination design. The project-list example below is hypothetical, not an Ampity customer migration.
Choose a version selector your infrastructure can preserve
| Selector | Check before choosing | |---|---| | URL path | Routing, documentation and SDK generation can expose both versions clearly | | Query parameter | Every relevant cache key and proxy preserves the parameter; omitted values have a documented meaning | | Dedicated request header | Clients can set it, logs record the selected version, and caches vary correctly | | Versioned media type | Content negotiation and unsupported representations are handled consistently |
Typical selectors include /v2/projects, ?api-version=2, API-Version: 2, and a versioned media type in Accept.
A path version need not force an unrelated service to change versions at the same time. A header does not make a design more sophisticated. Decide the scope of a version: one resource family, one API surface or another documented boundary.
For header-selected responses that are cacheable, set the relevant Vary behavior and configure intermediaries accordingly. Vary: API-Version or Vary: Accept can distinguish those request headers under HTTP caching rules. It does not independently make a personalized response safe to share.
Reject an unsupported explicit version predictably. If a legacy client omits the selector, keep its documented default during the migration. Silently changing that default to “latest” can break consumers that never opted in.
Confirm that the change needs a migration
List observable changes before deciding whether a new version is necessary. Include default filters, sorting, validation, error responses, enum values, authorization behavior and side effects.
An optional response field can be compatible with a client that ignores unknown fields, yet fail a strict deserializer. A new enum value can break an exhaustive switch. A schema comparison should therefore trigger consumer tests, not automatically approve a release.
Use representative SDK versions and captured, sanitized contract fixtures. If you cannot identify a consumer's behavior, record that uncertainty. An unknown consumer is not evidence that the change is harmless.
Security fixes may need a different timeline. Make an explicit risk and support decision for those cases rather than preserving an unsafe behavior indefinitely or treating an emergency restriction as a routine migration technique.
Worked example: migrate a project list to pagination
Suppose the existing endpoint returns a bare array:
[
{"id": "p_17", "name": "North"}
]The replacement returns a paginated envelope:
{
"items": [
{"id": "p_17", "name": "North"}
],
"next_cursor": null
}The response shape has changed. A client that loops directly over the old array will fail against the envelope. A hurried fix that reads only items may silently miss later pages when next_cursor is non-null.
In this example, use explicit /v1/projects and /v2/projects routes. Keep v1's documented limits, ordering and filtering unchanged while consumers adopt v2.
Make the consumer change testable
The migration guide should show how to read items, follow next_cursor until completion, handle an invalid or expired cursor, and preserve the required authorization on every request. It should state whether the list is live or represents a consistent snapshot.
| Consumer scenario | What the migration test must establish | |---|---| | No projects | The client handles an empty collection without treating it as a transport failure | | One page | The client stops when the continuation value is null | | Multiple pages | The client fetches every page it needs without duplicating or omitting records under the documented consistency model | | Authorization changes between pages | The client handles the denial without displaying data outside its current permissions | | Cursor is rejected | The client follows the documented recovery path instead of retrying forever | | Unsupported version | The client receives a stable error and does not fall back to an unintended representation |
Do not replay production writes to compare versions unless the replay mechanism prevents side effects. For this read example, an authorized shadow comparison may be useful, but it still adds load and must respect data access and retention constraints.
Choose the transition implementation
Parallel handlers can preserve both contracts while sharing domain logic. Their cost is maintaining and testing two public surfaces.
An adapter is useful only when it preserves the old semantics. Returning the first v2 page as the v1 array is wrong if v1 promised a larger or complete result. Fetching every v2 page behind the adapter may be expensive and still may not reproduce the old consistency behavior. Test those properties before relying on translation.
A new SDK can simplify adoption, but applications still have to deploy it and accommodate changed behavior. An SDK release is not evidence that its consumers migrated. Version webhooks, events and background jobs separately where they have their own contracts.
Publish notices with the correct header syntax
Deprecation means a resource is being discouraged for continued use. Sunset communicates when it is expected to become unavailable. They are separate dates and separate header formats.
RFC 9745 defines Deprecation as a Structured Field Date, represented with @ followed by epoch seconds. RFC 8594 defines Sunset using an HTTP date. Sunset must not be earlier than the deprecation date.
Here is a hypothetical notice, not a recommended support duration:
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://developer.example.com/migrations/projects-v2>; rel="deprecation"; type="text/html"The deprecation timestamp is January 1, 2027 at 00:00 UTC. The sunset is July 1, 2027 at 00:00 UTC. The example documentation host is a placeholder. Publish your own migration instructions before returning the link.
Define whether notices apply to one resource or an entire version. The headers are signals, not a replacement for the support policy or direct communication with affected owners. Some consumers will not surface response headers to their developers.
Deprecation itself does not instruct the client to accept degraded service. Do not gradually throttle a deprecated endpoint merely to force adoption. Maintain the agreed behavior during the support period, subject to explicit operational and security policies.
Measure migration at the consumer level
Request share alone can hide a critical integration that runs infrequently. A monthly export may matter even when it contributes little daily traffic.
Build a migration register with a stable client identity, owner, used endpoints, selected version, SDK or integration type, last observed activity, required business cycle and migration status. Do not retain raw credentials to identify clients. Where ownership is unknown, create an investigation item.
Track at least:
- Active consumers by version, including low-frequency jobs.
- Error and business-outcome differences during each consumer's cutover.
- Remaining endpoint or field dependencies.
- Confirmed owner acknowledgement and planned deployment.
- Exceptions, their owners and their review dates.
Distinguish “no requests observed” from “retired with owner confirmation.” Choose the observation period around the consumers' operating cycles and the agreed support terms. There is no universal six-month or twelve-month window that fits every API.
Use explicit cutover and retirement gates
| Gate | Evidence required | If the gate fails | |---|---|---| | Replacement ready | Documented contract, consumer fixtures, supported SDK examples and negative tests | Keep the new version limited while fixing gaps | | Consumer ready | Named owner has tested the actual integration and scheduled deployment | Keep the consumer on its supported contract | | Cutover healthy | Expected results, acceptable failures and completion of the relevant business workflow | Use the tested rollback or forward-fix plan | | Retirement ready | Remaining consumers are migrated, retired or covered by an approved exception | Reassess the sunset with the accountable owner | | Shutdown verified | Documented retired-route response and no unintended fallback to another version | Restore the intended boundary and investigate |
A rollback is possible only if the old contract still understands the data and side effects produced since cutover. Changing a database schema or emitting a new event shape can make an application-only rollback insufficient.
At retirement, choose and document the response for the old route. 410 Gone can express intentional permanent removal, but the Sunset specification does not mandate it or automatically configure it. Do not redirect incompatible write operations and assume the consumer's payload still means the same thing.
Remove old route configuration, unused credentials and code through the normal reviewed change process once their dependencies are resolved. Retain the migration record and enough operational evidence to investigate late callers.
For your next breaking change, complete the consumer register and one multi-page contract test before choosing a retirement date. Ampity's backend systems and API service covers implementation work where the acceptance criteria include consumer compatibility, migration evidence and production behavior.