API Version Sunset Policy¶
Lifecycle policy — instantiates Dependency-Aware Change Notification
Fixes in advance the guaranteed support lifetime and retirement schedule for every version of an interface, so dependents can count on a known window before the old version stops working.
Most change notices tell you about one change after it is decided. An API Version Sunset Policy does the opposite: it is a standing, published rule that binds the provider's own future behavior before any specific change exists. It promises, for every version of an interface, a minimum support lifetime, a defined sequence of retirement phases, and a grace period after cut-off — a contract that says "when we retire something, this is exactly how much runway you will get and how it will wind down." Its defining move is that the timeline is fixed and uniform in advance, so a dependent never has to negotiate or guess the window; they can read the policy once and plan every future migration against it. It is the schedule, not the message.
Example¶
A geospatial platform offers a geocoding API and publishes a sunset policy: every major version is supported for at least twenty-four months after its successor ships; the final six of those months are a "deprecated" phase in which responses carry a Sunset HTTP header with the exact cut-off date; and for ninety days after cut-off the old version stays reachable but read-only and rate-limited, returning a hard error only after that. When v3 launches, v2's clock starts automatically and the dates are computed off the policy, not negotiated case by case.
A two-person logistics startup that built on v2 never has to ask "how long do we have?" — the policy already answers it. They see the twenty-four-month floor, note the ninety-day read-only grace as their safety net, and schedule the migration for the third quarter rather than scrambling when the header first appears. The provider, meanwhile, can retire v2 without a bespoke negotiation with every caller, because the runway was promised the day v2 shipped.
How it works¶
- Publish a versioning contract. Fix, in writing and in advance, the support tenor (e.g., "supported ≥N months after the next major version") that applies to all versions uniformly.
- Define the retirement phases. A named sequence — active → deprecated → sunset → removed — with the machine-readable signals (
Deprecation/Sunsetheaders, changelog flags) that mark each transition. - Attach a grace period. Specify what "off" means: a hard cut-off, a read-only window, or a rate-limited tail that keeps the worst-prepared dependents alive a while longer.
- Compute dates off the rule. When a new version ships, the old version's timeline is derived from the policy automatically, so no version gets an ad-hoc runway.
Tuning parameters¶
- Support tenor — how long each version is guaranteed. Longer builds trust and lowers migration pressure but freezes the provider's ability to move and multiplies the surface that must be maintained.
- Concurrent supported versions — N-1, N-2, or more kept alive at once. More parallel versions ease dependents but raise operational and security cost.
- Grace-period depth — hard cut-off versus a read-only or rate-limited tail. A generous tail rescues stragglers but dilutes the finality of the date and invites procrastination.
- Exception conditions — whether the policy pre-declares circumstances (a security flaw, catastrophic adoption lag) under which a sunset can be extended or pulled forward. Naming them keeps discretion honest; leaving them open erodes the promise.
When it helps, and when it misleads¶
Its strength is predictability. Because the runway is fixed before any given change, dependents can plan on a calendar instead of reacting to a surprise, and the provider gains the moral standing to actually retire old versions. A policy is also the only fair way to treat a heterogeneous population uniformly — the sophisticated and the peripheral get the same guaranteed window.
Its failure mode is a policy that exists on paper but not in practice: a sunset that is quietly extended again and again teaches dependents that dates are negotiable, so they stop preparing — and the next real cut-off catches everyone. The subtler trap is Hyrum's Law[n1]: with enough users, every observable behavior of the interface has become someone's dependency, so a version retirement always breaks a caller who relied on something the contract never promised. The guarding discipline is to instrument real usage of the old version before the date, hold the published cut-off unless a pre-declared exception fires, and let the grace period — not endless slippage — absorb the stragglers.
How it implements the components¶
change_boundary_statement— the policy is the boundary in standing form: it declares, for any version, what stops being supported and exactly when active turns to removed.lead_time_requirement— the guaranteed support tenor is the lead time, fixed in advance and uniform across dependents rather than set per change.compatibility_bridge_or_grace_period— the read-only / rate-limited tail after cut-off is the bridge that keeps the least-prepared dependents running while they finish migrating.
It writes no per-caller instructions — that actionable_notice_payload is Deprecation Notice and Migration Runbook Notice — and confirms no one's readiness; that receipt_or_readiness_signal belongs to Notification Acknowledgement Tracker. The nearest twin is the Deprecation Notice: the policy fixes when support ends for all versions, whereas the notice is the in-band message that a specific thing is going away now.
Related¶
- Instantiates: Dependency-Aware Change Notification — supplies the standing timeline the whole notification system schedules against.
- Sibling mechanisms: Change Advisory Broadcast Workflow · Deprecation Notice · Emergency Change Alert · Maintenance Window Notice · Migration Runbook Notice · Notification Acknowledgement Tracker · Release Notes with Effective Date · Stakeholder Change Briefing · Subscriber Change Webhook
Editorial Notes¶
Form Classification¶
Form family: Rule, Policy & Commitment
Rationale: Fixes in advance the guaranteed support lifetime and retirement schedule for every version of an interface, so dependents can count on a known window before the old version stops working, making its operative form a standing constraint, permission, threshold, obligation, or conditional rule.
Independent corroboration: The frozen evidence defines API Version Sunset Policy as 'Fixes in advance the guaranteed support lifetime and retirement schedule for every version of an interface, so dependents can count on a known window before the old version stops working', so its operative form is Rule, Policy & Commitment.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Specialized
Rationale: Software lifecycle practice developed preannounced support windows, deprecation phases, compatibility bridges, and machine-readable sunset signals.
Related originating lineages:
- Law & Governance — Prospective notice and reliance protection provide a parallel governance logic.
- Organizational & Management Science — Dependency coordination and migration planning shape support tenors.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
The policy is a promise, not an event. Its value comes entirely from being believed, which is why the single most damaging thing a provider can do is honor it inconsistently — one extended sunset costs more credibility than the extension ever saved a straggler.
[n1] Hyrum's Law — "with a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." Named for engineer Hyrum Wright; it explains why a version retirement breaks callers even when the sunset window was generous and clearly announced. ↩