v1 Deprecation

6 months.

Overview

v1 deprecation is the discipline of retiring an old API version without breaking customer trust. A six-month window is the modern default and clears the way for v2 to become the supported surface; getting the mechanics right (sunset header, per-customer instrumentation, migration guide, active support) is what turns a forced migration into a predictable one.

• Six-month window. v1 stays available for six months after announcement. Real calendar time, real customer breathing room.
• Per-endpoint migration guide. v1-to-v2 mapping with code samples in every supported SDK. Friction drops to near zero for the common path.
• Sunset HTTP header plus per-customer logging. v1 responses carry the Sunset header so automated clients see the deadline; per-customer usage tracking surfaces who still calls v1 endpoints.
• Active migration support. Engineering and customer success help the long tail. The deprecation calendar is real, not a press release.

The approach

Announce the moment v2 is GA, instrument everything from day one, support migration actively. The discipline is mechanical; the trust the deprecation builds (or burns) is whatever the team's execution actually delivers.

• Announce on v2 GA. Deprecation clock starts the day v2 reaches general availability. Full window for every customer.
• Per-customer, per-endpoint instrumentation. Usage telemetry surfaces who calls what. Outreach targets the actual blockers.
• Personalised email with specific endpoints. Each customer sees their own v1 calls and the v2 equivalents. Actionable, not generic.
• Migration tooling plus public timeline. Automated helpers where possible; public deprecation calendar with all key dates. Transparency over surprise.

Why this compounds

Each clean deprecation teaches the team how to do the next one with less drama. Old surfaces stop costing engineering time, the architecture simplifies, customer trust survives the change. By year two, deprecation is a routine quarterly activity instead of a crisis.

• Reduced operational burden. Old APIs stop demanding engineering time. Capacity returns to current product.
• Cleaner architecture. Retiring v1 simplifies the codebase. Future changes get easier.
• Customer trust preserved. Predictable deprecation builds the loyalty unpredictable deprecation burns.
• Year-one investment, year-two habit. First deprecation is the investment; by year two, the runbook is mechanical.