Implementing API Deprecation Strategies

HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
Link: <https://api.example.com/v2/orders>; rel="successor-version"
Link: <https://docs.example.com/migrate-v1-v2>; rel="deprecation"

HTTP/1.1 200 OK
X-API-Warning: Endpoint deprecated. Use /v2/orders. Removed 2026-01-01.
Deprecation: true
Sunset: Sat, 01 Jan 2026 00:00:00 GMT

location ~ ^/v1/orders/(.*)$ {
  return 301 /v2/orders/$1$is_args$args;
}

# Optional: 308 preserves method for non-GET
location /v1/payments {
  return 308 /v2/payments;
}