Deprecation audit
Can you retire this API version without breaking customers?
Use this checklist before moving an endpoint version from deprecated to retired. The goal is to prove who still depends on it, show them a migration path, and define the cutover controls before enforcement begins.
Ready
Evidence is current, owners are named, and customer impact is observable.
Needs evidence
A decision is plausible, but one or more facts still need proof.
High risk
Unknown callers, unclear behavior changes, or missing enforcement controls remain.
1. Inventory the version
Confirm what is being retired.
- Current, deprecated, or retiring state exists for the version.
- Owning team is identified.
- Replacement version is documented.
- Sunset date and support window are known.
2. Prove who still depends on it
Map every active caller to an accountable owner.
- Consumers are mapped to credentials and organizations.
- Endpoint and version usage is visible by client.
- Last-seen timestamps are available.
- High-volume and business-critical consumers are labeled.
3. Validate migration path
Make the replacement version boring to adopt.
- Replacement endpoint behavior is documented.
- SDK or client library upgrade path exists.
- Error codes and response changes are listed.
- Sandbox or staging environment exists.
4. Communicate and enforce
Pair customer notice with a precise enforcement plan.
- Timeline is published.
- Owners have contact routes.
- Reminders are scheduled.
- Retirement enforcement behavior is known.
5. Monitor the cutover
Watch for the calls that should have disappeared.
- Logs and metrics are watched.
- Failed auth or retired-version calls are alertable.
- Rollback or extension owner is named.
- Post-retirement support plan exists.
Evidence to gather
- Endpoint list by version and environment.
- Credentials and client map with organization owners.
- Version usage export with last-seen timestamps.
- Migration guide for endpoint, SDK, and response changes.
- Customer notice copy and reminder schedule.
- Rollback criteria and extension decision owner.
Red flags
- Unknown credentials are still calling the retiring version.
- Business-critical consumers have not acknowledged the migration.
- The replacement version has undocumented error or response changes.
- No alert exists for retired-version traffic after enforcement.
- No owner can approve a rollback or support-window extension.
30/60/90 day retirement plan
30 days
Freeze scope, publish the migration guide, export caller usage, and notify accountable owners.
60 days
Track remaining usage, send reminders, validate staging migrations, and label exception requests.
90 days
Enforce retirement, monitor failed calls, route support, and hold the rollback criteria review.