Deprecation, Sunset, and Consumer Evidence

Working case

The permit service wants to retire its v1 case export. Daily dashboard traffic has moved to v2, so a single-day chart shows zero v1 calls. A monthly reconciliation job at district 29 still calls v1 on the first working day. The team extends the overlap window, contacts the registered integration owner, and sends deprecation and planned sunset information on v1 responses. It runs the job against a staging v2 representation and verifies downloaded bytes, field units, and permission scope. Only after a full job cycle with zero valid v1 use does the team schedule a reversible shutdown with an owner on call.

Implementation boundary

function mayRetireRoute(consumers, now, observationDays) {
  return consumers.every(client => client.migrated &&
    now - client.lastOldUseDay >= observationDays);
}
console.log(mayRetireRoute([{ migrated: true, lastOldUseDay: 7 }, { migrated: false, lastOldUseDay: 29 }], 63, 47));
// Output: false

Keep a registry of client owners, credentials or app identities, last-seen timestamps, and supported contract versions. Add response lifecycle signals at the resource boundary and publish migration instructions in the product’s internal documentation. Do not send a new header while silently changing behavior; leave the old resource functional during the announced window. Count authenticated consumer IDs or coarse cohorts under a privacy policy, excluding tokens and private record IDs from metrics. Observe a window long enough to include low-frequency jobs and offline clients. Provide a test environment or fixtures for the replacement. Before shutdown, rehearse a deny or route-toggle action and a rollback, including cached responses and job retries. After retirement, return a stable error or successor guidance rather than accidentally routing to a different schema.

Cost and boundaries

Keeping the old adapter alive consumes tests, deployment surface, and on-call attention. The longest supported consumer cycle sets a lower bound on evidence time; a monthly job cannot be cleared by a two-day quiet period. Per-consumer telemetry grows with the number of integrations, so use a bounded registry and aggregate operational views. A staged shutdown may cause a small number of controlled failures, but it reveals undiscovered callers before irreversible deletion. Measure migrated owners, last valid v1 use, old-route error rate, rollback duration, and whether each replacement workflow produces equivalent authorized output.

Failure trace

Turn off v1 after seven quiet days, then watch district 29’s month-end job fail with no export. A usage chart without a consumer inventory was weak evidence. Restore the adapter and add the job to migration planning. Another failure emits a deprecation signal but removes a response field the same day; existing clients break despite the warning. Preserve behavior until the planned retirement point. Finally, log full Authorization headers to identify callers and create a credential incident; use authenticated client identity from trusted server context instead.

Verification

Every registered consumer has an owner and migration evidence.
The observation window covers low-frequency usage.
The route can be disabled and restored without changing current permission policy.

Practice drill

Register three client cohorts: daily browser release 47, weekly partner sync 63, and monthly district 29 reconciliation. Announce a retirement 90 days away, then simulate all cohorts across a full cycle. Record which owner acknowledged the migration, which v2 contract test passed, and which v1 call remains. Turn off v1 behind a reversible control in staging, exercise retries and cached responses, then restore it. Define the public error and owner escalation for any residual client after the sunset.

Decision note

Retirement is an evidence-backed migration, not a traffic graph or header alone.

Common Mistakes

Equating deprecation with immediate shutdown.
Using only a daily traffic chart to infer no consumers remain.
Logging credentials to identify old-route callers.

Apply and check

Build Project: permit API client migration and review Web Development: API contract migration quiz.