Every API eventually goes away. The question was never whether but how, and the how is almost entirely a relationship question rather than a technical one.
Publish a deprecation policy before you need one — how much notice you give, how you communicate, how long a deprecated version keeps running. Consumers make adoption decisions partly on this, and having it written down in advance is worth more than any individual announcement.
When the time comes: announce early with a specific date, not “sometime next year.” Use your own usage
data to identify exactly who is calling the affected endpoints and contact them directly — you have
this data, and a generic blog post is not notice when you can see precisely who breaks. Mark it in the
contract and in the responses: OpenAPI has a deprecated flag, and the Deprecation and Sunset
HTTP headers exist so machines can see it too. Provide a migration guide that maps old to new
concretely, with examples. Keep a deprecation page listing what is going, when, and what to use
instead.
What burns people is the quiet sunset, the surprise, and the pattern of extracting as much value from developers as possible and then withdrawing the thing they built on. That is not just unkind; it teaches an entire market that your platform cannot be depended on, and that reputation outlives the API.
The best deprecation notices are boring. Clear, dated, specific, unremarkable. Boring is the goal.
