# Timelines, Communication and Usage Tracking — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/dep-timeline-comms

> Plan a realistic deprecation timeline, communicate through several channels and track who still uses the old version.

## 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.

```text
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.

**Quiz:** What should a retired endpoint return after its sunset date?

- [ ] 200 with empty data
- [x] 410 Gone with a helpful problem body
- [ ] A random 500
- [ ] Nothing, close the connection

*Answer:* 410 Gone with a helpful problem body. 410 clearly states the resource is permanently gone and can point to migration help.