Timelines, Communication and Usage Tracking

No surprises

Give clients enough time (public APIs often allow 6 to 12 months or more; internal ones less) and publish the plan up front: announcement date, new version availability, deprecation start, sunset date. Communicate through several channels: the changelog, developer email, a banner in the dashboard, response headers and sometimes brownouts (short scheduled outages that make sleeping clients notice). Track usage per client (API key, user agent) so you can contact the heaviest remaining users personally. Provide a migration guide with before/after examples, a mapping of changed fields, and test or sandbox access for the new version. When the date arrives, return a clear 410 Gone (with a problem body linking to the guide) rather than a confusing error. Extend the date if important clients are not ready and your policy allows it; never remove it silently.

A deprecation plan

Write it down and share it with the first announcement.

2026-10-01  v2 GA; v1 marked Deprecated (headers, docs, changelog, email)
2026-11-15  migration guide + sandbox; usage report per client sent monthly
2026-12-01  brownout #1: v1 returns 503 for 15 minutes
2026-12-15  brownout #2: 1 hour; contact remaining top callers directly
2026-12-31  Sunset: v1 returns 410 Gone with a link to the guide
2027-01-31  v1 code and routes removed

Measure before you switch off

Use the metric "requests to v1 in the last 7 days, grouped by client". When it reaches zero (or only clients you have contacted), retirement is safe.

Quick check: What should a retired endpoint return after its sunset date?

• 200 with empty data
• 410 Gone with a helpful problem body
• A random 500
• Nothing, close the connection