How should I run the sunset process when deprecating an endpoint in my public API?

Short answer: never silently delete an endpoint paying partners use. Run an announced, dated, measured sunset — communicate, signal it in the response, watch usage drop to zero, then remove it.

The core mistake is treating removal as an engineering event when it’s really a communication process; the code change that finally deletes the route is the last and smallest step of the whole thing.

1. Announce with a hard date and a migration path. Email + changelog + docs; give the partner a concrete replacement and a realistic window (weeks/months for paying B2B, not days). No date means no urgency, and no urgency means nobody migrates.
2. Signal it in the response itself. Add the RFC 8594 Sunset header + a Deprecation header + a Link header to the migration docs on every response from the doomed endpoint. That way machines and logs see it too, not just humans who ignore the email.
3. Measure usage per consumer. You can’t retire what you can’t see. Log calls by API key/partner; you need to know exactly who still calls it and how often, and reach those partners directly.
4. Run brownouts before you cut. As the date approaches, apply short, scheduled outages (return 410/503 for a few minutes, escalating the duration). This surfaces integrations that ignored every header and email while the impact is still reversible.
5. Return the right status on removal. Not a silent 500; return 410 Gone (or 404) with a body that explains the replacement. Keep that explanatory response up for a long time after removal.
6. Keep an escalation valve. For a big paying partner mid-migration, a temporary allowlist/extension beats breaking their production. Contractual/SLA reality outranks a tidy deprecation calendar. Just document who got an extension and until when, so the valve doesn’t quietly become permanent.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"; type="text/html"

Bottom line: personally I’d instrument per-partner usage first, then publish a dated sunset with those headers on every response, run a couple of brownouts near the date, and only cut when usage is near zero — while leaving a manual extension valve for the one partner who always misses the memo. In a public API, reputation is lost with a single silent removal.