API Breaking Changes: Deprecation and Migration Guide

An API breaking-change rollout is an operational migration, not just a new version number. The provider must identify affected consumers, publish the replacement contract, run a safe transition, communicate deprecation, measure migration, and define when the old behavior can be retired.

This guide covers that lifecycle. For definitions and a comparison of URI, header, query, and media-type versioning, see API Versioning Strategies and Best Practices.

What Counts as an API Breaking Change?

A breaking change makes an existing, contract-compliant client fail or behave incorrectly without a client update.

Classify changes against the published contract and observed consumers. Source compatibility, wire compatibility, and behavioral compatibility are different; a schema diff cannot identify every behavioral break.

API Deprecation and Migration Lifecycle

flowchart LR
    A[Assess impact] --> B[Publish replacement]
    B --> C[Run versions in parallel]
    C --> D[Announce deprecation]
    D --> E[Measure client migration]
    E --> F{Retirement criteria met?}
    F -->|No| C
    F -->|Yes| G[Sunset and retire]

1. Inventory Consumers and Dependencies

Before announcing a date, identify:

• active client identities, SDK versions, and integration owners;
• request volume by version and endpoint;
• consumers that cannot be identified from gateway or application telemetry;
• internal jobs, partner integrations, mobile apps, and long-lived devices with slower release cycles;
• contractual, regulatory, or support commitments that constrain retirement.

Unknown consumers are a migration risk. Improve attribution before relying on a deadline that cannot be measured.

2. Publish the Replacement Contract

Provide the new API description, examples, changelog, and migration guide before asking clients to move. The guide should include:

• a field-by-field or operation-by-operation change map;
• old and new request and response examples;
• authentication or permission changes;
• SDK and test-environment availability;
• rollback guidance when a client migration fails;
• a contact and escalation path.

Keep the replacement documentation on a stable URL. A deprecation notice without a usable migration path creates urgency but not progress.

3. Run Old and New Versions in Parallel

Parallel operation gives consumers time to test and migrate. An API gateway or application router can select the upstream version from a path, header, media type, or other documented key.

flowchart LR
    A[Client request] --> B[API gateway]
    B -->|v1 selector| C[Existing API]
    B -->|v2 selector| D[Replacement API]
    C --> E[Version-level metrics]
    D --> E

The routing rule must be deterministic. Do not silently move a client between incompatible contracts without an explicit migration or controlled experiment.

4. Communicate Deprecation

Use several channels because no single signal reaches every integration owner:

• developer portal and API documentation;
• changelog and migration guide;
• direct notification to known owners;
• SDK or client-library release notes;
• response metadata for clients that inspect it.

RFC 9745 defines the Deprecation HTTP response header. Its value is a Structured Field Date, represented as an integer prefixed with @. A Link header with rel="deprecation" can point to the policy or migration guide.

Deprecation: @1798761600
Link: <https://developer.example.com/migrations/v2>; rel="deprecation"; type="text/html"

The header is a hint for the resource in that response. Documentation should define any broader scope, such as an entire API version.

5. Measure Migration Progress

Track progress by identifiable consumers, not only total traffic. A low-volume integration can still be business-critical.

Useful measures include:

• active clients still calling the old version;
• old-version requests by endpoint and owner;
• migration test failures and support requests;
• error rates and latency for both versions;
• clients that tried the new version and returned to the old one;
• SDK or application releases that include the migration.

Create an exception process for consumers that cannot meet the initial timeline. An exception should have an owner, reason, mitigation, and revised date.

6. Announce Sunset Separately

Deprecation and sunset are different states. A deprecated API still operates but is no longer recommended. A sunset date indicates when the resource is expected to become unavailable.

RFC 8594 defines the Sunset response header as an HTTP-date:

Sunset: Fri, 31 Dec 2027 23:59:59 GMT
Link: <https://developer.example.com/migrations/v2>; rel="sunset"; type="text/html"

Do not send a Sunset date merely to create pressure. Publish it when the provider has an approved retirement plan and affected consumers have a credible path forward.

7. Retire with Explicit Gates

Define retirement gates before the final date. For example:

• all high-criticality consumers have migrated or have approved exceptions;
• old-version traffic is understood and below the agreed threshold;
• the replacement meets reliability and security requirements;
• support, incident response, and rollback procedures are ready;
• documentation and SDK defaults point to the replacement;
• the gateway and application removal plan has been tested.

After retirement, return a documented response or remove the route according to the published policy. Monitor client failures so unexpected dependencies are visible quickly.

Plan a Low-Risk Version Rollout

A rollout plan should separate contract migration from infrastructure deployment.

The length of each phase depends on client release cycles, risk, contracts, and operational evidence. A universal 30-, 90-, or 180-day policy is rarely appropriate for every API.

Use an API Gateway During Migration

An API gateway can support a migration when its routing and observability are configured deliberately:

• route explicit version selectors to separate upstreams;
• apply authentication and traffic policies consistently across versions;
• record version, client identity, route, status, and latency;
• direct a controlled cohort to the replacement when the contract permits it;
• revert routing quickly when readiness criteria fail.

The gateway does not decide whether a change is compatible or whether a consumer is ready. Those decisions belong to the API contract, tests, owner communication, and migration governance.

Breaking-Change Review Checklist

Before release:

• The breaking behavior is documented precisely.
• A compatible alternative was considered and rejected with a reason.
• The replacement contract and migration guide are published.
• Known consumers and owners are inventoried.
• Old and new versions can be observed separately.
• Test and rollback procedures cover both provider and consumer failure.

Before retirement:

• Deprecation and sunset are communicated as separate lifecycle states.
• Remaining traffic is attributed to known consumers or investigated.
• Critical consumers migrated or received approved exceptions.
• Documentation, SDKs, examples, and onboarding use the replacement.
• Retirement and rollback steps were rehearsed.

FAQ

What is the difference between deprecation and sunset?

Deprecation signals that an API or resource is no longer recommended and may be removed in the future. Sunset identifies when it is expected to become unavailable. RFC 9745 and RFC 8594 define separate HTTP headers for these states.

Does every breaking change require a new API version?

An incompatible public-contract change normally needs a separate contract boundary or a coordinated migration. The boundary can be a new path, header value, media type, endpoint, or other explicit mechanism. Review API versioning strategies before choosing it.

How long should an API deprecation period last?

Base the period on consumer release cycles, criticality, contracts, migration effort, and measured readiness. Avoid a universal duration that ignores the actual client population.

Can a gateway migrate clients automatically?

Only when old and new contracts are compatible for those clients or a tested transformation preserves the contract. Do not silently translate incompatible semantics without explicit ownership and validation.

Related Guides

• API Versioning Strategies and Best Practices
• API Lifecycle Management
• Writing Clear and Concise API Documentation
• A/B Testing and Canary Releases with an API Gateway
• What Is an API Gateway?