Salesforce scheduled the retirement of Platform API versions 21.0 through 30.0 for the Summer '23 release and later postponed it to Summer '25, having retired versions 7.0 through 20.0 in Summer '22. After retirement, REST calls on a retired version return 410 Gone. What does a postponement of that size tell you about deprecation as a mechanism, and what would you build so that yours does not slip?

The situation they were in

A platform whose customers integrate deeply and upgrade slowly. Managed packages, middleware connectors, and scripts written years ago by consultants who have moved on all pin an API version, and the organisation running them frequently does not know they exist. Salesforce has been retiring old versions in cohorts for years — 7.0 through 20.0 went in Summer '22 — so the mechanism works. It simply does not work to a date: the 21.0-30.0 cohort was announced for Summer '23 and carried forward in successive release notes.

What a postponement actually tells you

The date was never the constraint. The residual traffic was. A deprecation date is a forecast about other people's behaviour, and the only thing that moves the decision is the volume of calls left on the old version falling to a level where the remaining breakage is commercially acceptable.

That reframes the whole exercise. The question is not "when do we turn it off" but "what makes the curve fall faster".

What the announcement bought even though the date moved

It is not wasted effort. An announcement reliably stops new integrations landing on the deprecated version and moves the largest, most attentive customers, who have change programmes and account teams. What an announcement does not move is the long tail: the integration nobody owns, running on a schedule, in an org where the person who built it has left.

What to build so yours does not slip

1. Per-consumer usage telemetry at version granularity, tied to an identity you can contact. Without it, a retirement date is a guess and the escalation on the day comes from a customer you did not know existed. This is the single highest-value artefact and almost nobody builds it early enough.
2. Brownouts. Announced, scheduled windows — 30 minutes, then two hours, then a day — during which the old version returns its retirement error. A brownout produces more migration than six months of email, because it converts an abstract future date into a failed job in the customer's own monitoring, while remaining fully recoverable.
3. Errors that name the fix. A 410 whose body carries the sunset date, the replacement version and a link is worth more than the status code alone, because the person reading it is a stranger debugging at speed.
4. Machine-readable sunset signalling on live responses — Deprecation and Sunset headers, as standardised in RFC 8594 — so tooling and SDKs can surface it without anyone reading a blog post.
5. A published policy with a minimum notice period, so the date is credible. A date announced without a policy behind it will be tested, and it will move.

What it costs to keep old versions alive

Not the branch in the request path, which is cheap. The real cost is that the internal model cannot change shape while any live version depends on its old shape, so every retained version is a constraint on the data model and on every future feature that touches it. That cost is invisible in a code review and enormous in aggregate, which is why platforms with long version support end up with a transformation layer whose job is to keep the past alive.

Where copying it would be a mistake, and when not to run a long deprecation

This shape is specific to an unknown, contractually protected, slow-moving consumer population. A platform with 200 known internal consumers that runs a multi-year deprecation is inflicting the cost without the constraint: there, consumer-driven contract tests plus a coordinated change is a matter of weeks. The mistake to avoid is treating an internal interface as though its consumers were anonymous, which is how an organisation ends up supporting seven live versions of something four teams call.