api-versioning-deprecation-planner

Announce deprecation 6+ months in advance, run both versions in parallel, and add Deprecation and Sunset headers to old responses. Track usage metrics to identify remaining consumers and offer migration support before shutting down the old version.

URL versioning (e.g., /api/v1/users) is recommended because it is clear, easy to route, and simple to document. Header versioning keeps URLs clean but is harder to test, while query parameter versioning is easy to implement but not RESTful.

Breaking changes include removing endpoints, parameters, or response fields, changing field types, and making optional fields required. Non-breaking changes include adding endpoints, optional parameters, response fields, or new status codes.

Return Deprecation: true, a Sunset header with the shutdown date in HTTP-date format, a Link header pointing to the replacement version, and a Warning header with a human-readable migration message.

Run v1 and v2 routers in parallel, use an adapter pattern where v1 endpoints internally call v2 and transform responses, or gate new behavior behind feature flags. Monitor per-version request metrics to track migration progress.