1. LandOffer
  2. Blog
  3. All articles
  4. Deprecate an API Without Surprising Its Consumers

Engineering Practice

Deprecate an API Without Surprising Its Consumers

Build a consumer migration ledger and complete notices that distinguish deprecation from retirement. A fictional monthly caller, unfinished migration, and unattributed traffic delay shutdown; isolated date checks do not prove real consumer readiness.

9 min readLandOffer team

Deprecate an API by giving consumers a usable replacement, a clear scope and timeline, and a way to confirm migration before retirement. Identify who still depends on the old behavior, communicate through more than one channel, and review remaining use with an accountable decision owner. Publishing a date or adding a response header does not establish that every consumer received the message or completed the change.

This LandOffer.ai guide contains a completed consumer ledger, an initial notice, and a revised retirement decision. The service, callers, traffic, people, dates, and communications are fictional teaching examples. Only an isolated Python check of authored dates and ledger arithmetic was actually run. No real API, account, consumer, logs, credentials, deployment, or notification was accessed or changed. Primary sources were checked October 27, 2026; later dates below belong to the invented scenario.

A person holding a route notice gestures toward a v2 bridge while loaded carts continue toward the open v1 bridge.

Separate deprecation from retirement

Deprecation tells consumers that a resource is no longer the recommended dependency and that they should plan a transition. Retirement is the separate decision to make the affected resource unavailable. An announcement that the old version is deprecated does not by itself say that today's requests must stop working.

Booking.com's published deprecation page illustrates a provider separating deprecation dates, sunsetting dates, affected solutions, and migration guidance. Those timelines belong to that provider and solution. They do not establish a universal notice period or permission to retire another organization's API after the same interval.

For your API, identify the exact endpoints, methods, versions, fields, or behaviors affected. State what remains supported during transition and what the replacement does not cover. Avoid a vague “v1 is going away” notice when only a subset is affected, or a promise of complete compatibility when clients need to change their assumptions.

In the fictional case, API owner Rosa proposes retiring GET /v1/catalog/items in favor of GET /v2/catalog/items. Other v1 resources remain outside this change. The migration guide must explain the replacement's cursor-based pagination and display_name field instead of the old page parameter and name. This article does not assess whether that contract change is backward compatible; consumer migration and lifecycle decisions are its focus.

Inventory consumers by workflow and accepted owner

Start with the authorized sources your organization permits: API inventory, client registrations, owned application documentation, and approved usage aggregates. Do not paste access tokens, raw payloads, personal data, or secrets into a migration spreadsheet. An opaque client identifier can be enough to route an ownership question through the appropriate team.

Map a caller to the workflow that would fail, not just a credential or repository name. A nightly job and a monthly export need different observation windows. A shared credential may cover several workflows, while a single consumer may use several client IDs. Document those identity limits before treating a count of IDs as a count of migrated applications.

For each consumer, distinguish notice delivered, acknowledgement received, migration work accepted, replacement behavior checked, production transition recorded, and old use reviewed. Those are separate states. An owner reading the guide is not a completed upgrade, and a successful replacement request is not proof that pagination, errors, and the full workflow remain correct.

The fictional January 15 readiness review uses an approved aggregate window of January 2–15 inclusive. These counts and attestations are authored inputs, not actual telemetry. The fourteen-day window is an illustrative operational choice, not a recommended safe interval for every service.

Consumer and dependency Notice and accepted work January 15 evidence Readiness decision and next owner
Web dashboard; frequent catalog display Ira acknowledged and accepted the change Owner records workflow comparison and production switch; zero old calls in the window, with replacement calls present Ready for this recorded workflow, subject to final review; Ira remains the contact
Nightly catalog worker Marta acknowledged; migration slot accepted for January 22 140 old calls; replacement exercised only in the fictional test environment Not migrated. Marta owns completion and workflow evidence, not merely a new successful request
Monthly inventory export Tessa confirmed ownership January 12; work not completed Zero old calls in the window, but last old run January 1 and next scheduled run February 1 Not ready. Tessa must migrate and check a representative run; silence in this window is insufficient
Unattributed client alias Owner has not been found; delivery/acknowledgement unknown 37 old calls, most recent January 15; workflow and schedule unknown Blocker remains. SRE Leo accepts ownership discovery, not an assurance that the consumer can be removed

There are 177 old requests in the authored window, but three unresolved consumer rows. The monthly export belongs among them despite its zero count. The dashboard's readiness is a bounded statement about its recorded workflow, not proof that the entire API has no undiscovered callers.

Keep the evidence scope beside the conclusion. Sampling, retention gaps, shared identities, disabled logging, and infrequent jobs can all limit what a usage view tells you. If the observation coverage is unknown, record it; do not label missing information as inactivity. Owner confirmation and a representative operating cycle can reveal a dependency that a short request window misses, as the monthly export does here.

Make the notice actionable before adding machine signals

Before the November 2 announcement in this fictional case, the service lead accepts operating the existing contract through the initial transition window. Rosa’s completed notice reads:

Change announced November 2, 2026: GET /v1/catalog/items is deprecated from today. The current retirement target is February 1, 2027 at 00:00 UTC. This scope excludes other v1 resources.

Use GET /v2/catalog/items. The versioned migration guide explains cursor pagination, the display_name replacement, examples, and known gaps. Do not change only the URL and assume the whole workflow is equivalent.

During the transition the old resource remains available under its existing contract; no new dependency should be built on it. Contact the API migration owner through the published support route with your workflow owner, expected run cycle, planned migration date, and blockers. Do not send credentials or private payloads.

We will review readiness January 15, including infrequent and unattributed callers. Acknowledgement is requested from known owners; reading a response header does not complete migration. Any revised retirement date and scope will be published in the same guide, change log, and direct follow-up to known contacts. No individual exception is approved by this notice.

This is a full authored message, not a communication sent to anyone. The service owner must have authority and capacity to maintain the old contract during the stated transition. If support, contractual, or security constraints limit that promise, resolve and state them before issuing the notice. Do not invent an exception process that the organization cannot operate.

Provide the replacement guide and support route where consumers actually work: maintained developer documentation, version change logs, SDK or integration guidance, and the organization's approved direct channels. Track meaningful acknowledgements rather than assuming a broadcast reached every owner. Headers are an additional signal, especially for callers who inspect responses; they are not the entire communication plan.

Use header dates precisely and keep their scope clear

RFC 9745, published March 2025, defines Deprecation as a structured date and a related link to explanatory documentation. The field concerns the response's resource unless a broader scope is documented. The header itself does not change resource behavior. RFC 8594 defines Sunset using an HTTP date for expected unavailability; it is a hint, not a guarantee of exact availability or a particular error status afterward.

The authored initial date examples are:

Deprecation: @1793577600
Sunset: Mon, 01 Feb 2027 00:00:00 GMT

The first value represents November 2, 2026 at 00:00 UTC. Do not put an HTTP-date string into that field merely because the Sunset field uses one. RFC 9745 also requires the sunset timestamp not to precede the deprecation timestamp. A documentation link should lead to the authentic, maintained migration policy for the affected resource; it does not make every other endpoint deprecated.

These two dates were round-tripped offline using Python 3.12.14 standard-library date utilities. The same check confirms that a sunset before the deprecation date fails the example's chronology rule. This checks only the authored date values and their order; it is not full structured-field parser conformance, a deployed response capture, or verification that a real client reads either header. Wire syntax, server configuration, intermediaries, and client handling need their own authorized checks.

A hand points to a Monthly calendar wheel beside a loaded cart near the v1 bridge, with a v2 bridge farther away.

Let remaining use change the retirement decision

At the January 15 review, Rosa cannot approve the February 1 retirement from this ledger. The nightly migration is unfinished, the monthly job has not exercised the replacement, and an active alias remains unattributed. The roadmap date does not resolve those unfinished migrations and ownership questions. Leo's accepted ownership search also does not make him the consumer's migration owner.

Rosa and the service lead agree on a supported extension to March 1, 2027 at 00:00 UTC. The service lead accepts keeping the existing resource operational and deferring a planned maintenance refactor to provide capacity. They record the extension through the organization's normal approval process in the fictional story. This is an accepted bounded decision, not a claim that keeping an old API indefinitely is costless or always appropriate.

The completed January 16 update reads:

Retirement date changed: March 1, 2027 at 00:00 UTC replaces the previously announced February 1 target for GET /v1/catalog/items. The November 2 deprecation date and scope remain unchanged. The guide, change log, response configuration, and known-owner follow-ups now reflect the revised date in this example.

Three readiness rows remain unresolved: the nightly worker, monthly export, and unattributed active alias. Marta owns the accepted January 22 migration work; Tessa owns the representative monthly-workflow check; Leo owns locating the missing owner. Rosa owns the next retirement decision. No consumer is marked migrated solely because its request count is zero.

Review again January 29. Do not enable a client cutover or disable the old resource solely from this update. Record replacement checks, rollout evidence, residual old calls, infrequent schedules, and remaining exceptions before the service owner authorizes retirement.

No real notice or configuration was changed. In the authored record, the revised Sunset value is Mon, 01 Mar 2027 00:00:00 GMT; the deprecation value stays unchanged. The local fixture confirms that this later date is after both the original target and deprecation date. It does not establish that any consumer received the update or that the extra month will be enough.

The January 29 review has not occurred in this case. Keep the unfinished rows and accepted actions visible. If the organization cannot extend further, its authorized owners must decide how remaining consumers and risks will be handled through the actual policy. Do not turn “we tried contacting them” into consent, erase unknown consumers, or execute retirement against a date that the published notices have replaced.

Record retirement as a separate authorized action

Before retirement, reconcile the consumer inventory with the available observation coverage, owner confirmations, replacement workflow checks, exceptions, and service-operating plan. Confirm who approves the final action and who will observe errors and handle escalation afterward. An implementation checklist should also preserve the actual recovery constraints; a promise to restore the old endpoint is meaningless if the necessary data or dependencies will no longer exist.

The ledger and notices above finish with an extension and open work, not an invented successful shutdown. A responsible plan can expose that retirement is not ready. Use your organization's real authority and controls for eventual changes rather than treating this article as approval to disable an API.

Inventory one affected resource, identify unresolved consumers, and take a notice with the replacement, scope, support commitment, owner, and review point to the authorized service lead. LandOffer.ai publishes this engineering guide; it does not inspect your consumers or perform migrations. Keep the final retirement decision tied to the evidence and explicit approval, rather than the existence of an announcement alone.

Sources and Further Reading