A platform must remove a widely-used internal API. How should the deprecation be run?

The sequence

1. Measure usage per consumer, before announcing anything. Which teams, which endpoints, how often. This converts an unbounded political problem into a named list, and it is the step that makes everything else possible.

2. Provide the replacement first, and make migrating to it demonstrably better — not merely different. A deprecation announced before the replacement exists is an unfunded mandate.

3. Build the migration tooling, or do the migration. Telling teams to migrate is a request that competes with their roadmap and loses. For internal APIs the platform team can and should open the changes.

4. Announce with a real date, communicated well ahead, with the reason and the migration path.

5. Instrument warnings — in responses, in logs, in the developer dashboard — so a team using the old path learns from the system rather than from an announcement they missed.

6. Track migration progress publicly, per consumer, so the remaining set is visible and shrinking.

7. Brownouts before removal. Disable the old path for short, announced periods — an hour, then a day. Teams that missed every notice discover it safely, and it is reversible. This is the technique that converts a risky removal into a sequence of measurements.

8. Remove, with the ability to restore quickly for a defined period.

What makes it fail

• Announcing without measuring, so the scope is unknown and the timeline is arbitrary.
• No replacement, or one that is worse.
• Migration left entirely to consumers, which is how deprecations run for years.
• No brownout, so removal is the first time anyone discovers a dependency.
• Repeated extensions, which teach teams that deadlines are negotiable and make the next deprecation harder.

The obligation the platform carries

Internal consumers are as broken by a breaking change as external ones. A platform that breaks its users loses them permanently — they build their own and never return. The visibility advantage of internal APIs shortens the timeline; it does not remove the obligation.