patterntypescriptMajor

API Deprecation Strategy: Sunset headers and migration guides

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

deprecationsunsetversioningmigrationrfc-8594lifecyclebreaking-change

Error Messages

410 Gone

Problem

Removing or changing API endpoints without adequate warning breaks consumers. Many teams just delete endpoints or change behavior without giving consumers time to migrate.

Solution

Use the Deprecation and Sunset HTTP headers (RFC 8594). Set Deprecation: true and Sunset: <HTTP-date> on deprecated endpoints. Log deprecation warnings server-side per consumer. Maintain old behavior until sunset date, emit migration guides in response Link headers.

Why

Structured deprecation gives consumers a contractual migration window. Machine-readable headers allow SDK authors to surface warnings automatically in developer tools.

Gotchas

Sunset dates must be communicated via email/changelog before the header is added — the header alone is insufficient for discovery.
Never change the behavior of a deprecated endpoint before the sunset date.
Monitor usage of deprecated endpoints to identify consumers who have not migrated.

Code Snippets

Deprecation headers on an endpoint

app.get('/v1/users', (req, res) => {
  res.setHeader('Deprecation', 'true')
  res.setHeader('Sunset', 'Sat, 01 Jan 2026 00:00:00 GMT')
  res.setHeader('Link', '</v2/users>; rel="successor-version"')
  // existing handler logic
  res.json(users)
})

Revisions (0)

No revisions yet.