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.
Low because no immediate runtime failure occurs, but surprise removal of deprecated endpoints causes production outages in downstream integrations with no graceful migration path.
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.
ID: saas-api-design.api-docs.api-deprecation-strategy
Severity: low
What to look for: Enumerate all API versions present. Check whether the project has any mechanism for communicating API deprecation to consumers. Look for: Deprecation response headers on older endpoints, Sunset headers with a date when the endpoint will be removed, deprecation notices in OpenAPI spec (deprecated: true on endpoints), changelog or migration guide documentation, middleware that logs or counts requests to deprecated endpoints.
Pass criteria: At least one of: a documented deprecation policy (in README or API docs), Deprecation and Sunset headers on any endpoints flagged for removal, or OpenAPI deprecated: true markers used consistently.
Fail criteria: No deprecation mechanism of any kind, and multiple API versions or superseded endpoints exist with no signaling to consumers.
Skip (N/A) when: The API is in v1 with no deprecated endpoints and no versioning history. Signal: all routes are in v1, no parallel versions exist, no endpoints marked as old or superseded.
Detail on fail: Example: Old /api/v1/user exists alongside /api/v2/user with no Deprecation header. Note the gap (e.g., "Old /api/v1/user endpoint exists alongside /api/v2/user with no Deprecation header; no sunset date communicated"). Max 500 chars.
Remediation: Establish a lightweight deprecation signaling mechanism in src/middleware.ts or route handlers. The standard approach uses two HTTP response headers:
// src/middleware.ts — add to deprecated routes
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 see whether any clients are still using them before the sunset date. Document the deprecation in your changelog or API reference. This gives consumers time to migrate without surprises.