API deprecation strategy defined

API consumers who call deprecated endpoints with no sunset signaling have no way to know they should migrate until the endpoint disappears and their integration breaks in production. The absence of deprecation headers violates ISO-25010:2011 compatibility.interoperability and maintainability.modifiability: the API surface cannot evolve without causing surprise breakage to consumers who were never warned. Deprecation and Sunset headers are RFC-standard mechanisms that monitoring tools, API gateways, and SDK generators already understand.

Add RFC-standard deprecation headers to superseded endpoints in src/middleware.ts or route handlers — no new dependencies required:

// src/middleware.ts — add to deprecated route responses
response.headers.set('Deprecation', 'true')
response.headers.set('Sunset', 'Sat, 01 Jan 2027 00:00:00 GMT')
response.headers.set('Link', '</api/v2/users>; rel="successor-version"')

Log requests to deprecated endpoints so you can confirm actual usage before the sunset date — if nobody is calling it, you can remove it early; if traffic persists, you know to reach out to consumers. Add a deprecated: true marker to the corresponding endpoint in your OpenAPI spec. Document the deprecation timeline in your changelog or API reference at the same time you add the headers.