Deprecation Headers

title: "Deprecation Headers — Sunset and Deprecation Response Headers" description: "Deprecation headers (Deprecation, Sunset) warn API clients about upcoming version retirement through standard HTTP response headers with clear timelines." date: 2026-06-28 lastmod: 2026-06-28 weight: 21 tags: [apis, versioning] }

Deprecation headers communicate version retirement through the Deprecation and Sunset HTTP response headers, giving clients machine-readable deprecation warnings.

What You'll Learn

• Deprecation header
• Sunset header
• Deprecation workflow

Why It Matters

Clients need automated ways to detect deprecation. Manual emails are missed. Deprecation headers provide programmatic warnings.

Deprecation Flow

sequenceDiagram
    Client->>API: GET /v1/users
    API->>Client: 200 + Deprecation: true
    API->>Client: Sunset: Sat, 31 Dec 2026 23:59:59 GMT
    Client->>Client: Log warning, schedule migration
    Client->>API: GET /v2/users (migrated before Sunset)

Code Examples

# Deprecation header middleware
from datetime import datetime, timedelta

DEPRECATED_VERSIONS = {
    '1': {
        'deprecated': True,
        'sunset': 'Sat, 31 Dec 2026 23:59:59 GMT',
        'migration': '/v2/users'
    }
}

@app.after_request
def add_deprecation_headers(response):
    version = getattr(request, 'api_version', None)
    if version and version in DEPRECATED_VERSIONS:
        info = DEPRECATED_VERSIONS[version]
        if info['deprecated']:
            response.headers['Deprecation'] = 'true'
            response.headers['Sunset'] = info['sunset']
            response.headers['Link'] = f'<{info["migration"]}>; rel="successor-version"'
    return response

# Per-endpoint deprecation
@app.route('/v1/users')
def get_users_v1():
    response = jsonify(users_v1())
    response.headers['Deprecation'] = 'true'
    response.headers['Sunset'] = 'Sat, 31 Dec 2026 23:59:59 GMT'
    response.headers['Link'] = '</v2/users>; rel="successor-version"'
    return response

// Express deprecation middleware
function deprecationMiddleware(deprecatedVersion, sunsetDate, migrationPath) {
  return (req, res, next) => {
    if (req.path.startsWith(`/${deprecatedVersion}`)) {
      res.set({
        'Deprecation': 'true',
        'Sunset': sunsetDate,
        'Link': `<${migrationPath}>; rel="successor-version"`
      });
    }
    next();
  };
}

app.use('/v1', deprecationMiddleware('v1', 'Sat, 31 Dec 2026 23:59:59 GMT', '/v2/users'));

# Client-side deprecation monitoring
import requests

def api_request(url, headers=None):
    response = requests.get(url, headers=headers)
    if response.headers.get('Deprecation'):
        sunset = response.headers.get('Sunset')
        link = response.headers.get('Link')
        print(f"WARNING: {url} is deprecated. Sunset: {sunset}. Migration: {link}")
        log_deprecation_warning(url, sunset, link)
    return response

Common Mistakes

1. No Sunset Header

Deprecation without a sunset date doesn't tell clients when to migrate.

2. Sunset Without Deprecation

Setting sunset without deprecation is confusing.

3. No Migration Link

Tell clients where to go. Include Link header with successor-version rel.

4. Deprecation Without Notice

Deprecate in a version first, then remove in a later major version.

5. No Logging on the Server

Track how many requests still use deprecated versions.

Practice Questions

1. What does the Deprecation header indicate?
2. What does the Sunset header indicate?
3. What Link rel value indicates the successor version?
4. How far in advance should you set Sunset?
5. How do clients detect deprecation?

Answers:

1. The response is from a deprecated API version.
2. The date when the deprecated version will be removed.
3. rel="successor-version".
4. At least 6-12 months from the deprecation announcement.
5. Check Deprecation, Sunset, and Link response headers.

Challenge: Implement a deprecation header system. Add middleware that adds Deprecation and Sunset headers for deprecated versions.

FAQ