HTTP Deprecation Policy

Sets HTTP deprecation headers on the outgoing response following the IETF HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link headers.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

config/policies.json
 
{
  "name": "my-http-deprecation-outbound-policy",
  "policyType": "http-deprecation-outbound",
  "handler": {
    "export": "HttpDeprecationOutboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "deprecation": true,
      "link": "https://example.com/docs/v2-migration",
      "sunset": "2025-06-30T23:59:59Z"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be http-deprecation-outbound.
• handler.export <string> - The name of the exported type. Value should be HttpDeprecationOutboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• deprecation (required) <undefined> - The deprecation value. Use true for already deprecated, an ISO 8601 date string for a specific date, or a Unix timestamp number.
• sunset <string> - An ISO 8601 date string indicating when the endpoint will be removed. Sets the Sunset header.
• link <string> - A URL to documentation about the deprecation or migration guide. Sets the Link header.

Using the Policy

This policy adds HTTP deprecation headers to outgoing responses following the IETF HTTP Deprecation Header standard. It supports the Deprecation, Sunset, and Link headers to signal to API consumers that an endpoint is deprecated.

Configuration

• deprecation (required): The deprecation value. Use true to indicate the endpoint is already deprecated, an ISO 8601 date string with timezone offset (e.g. "2024-12-31T23:59:59Z") for a specific deprecation date, or a Unix timestamp number.
• sunset: An ISO 8601 date string with timezone offset indicating when the endpoint will be removed. Sets the Sunset header.
• link: A URL to documentation about the deprecation or a migration guide. Sets the Link header.

Usage

Apply this policy to outbound responses in your route configuration:

Code
 
{
  "policies": [
    {
      "name": "http-deprecation-policy",
      "policyType": "http-deprecation-outbound",
      "handler": {
        "export": "HttpDeprecationOutboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "deprecation": "2025-01-15T00:00:00Z",
          "sunset": "2025-06-30T23:59:59Z",
          "link": "https://example.com/docs/v2-migration"
        }
      }
    }
  ]
}

If the endpoint is already deprecated and you don't need a specific date, you can set deprecation to true:

Code
 
{
  "policies": [
    {
      "name": "http-deprecation-policy",
      "policyType": "http-deprecation-outbound",
      "handler": {
        "export": "HttpDeprecationOutboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "deprecation": true,
          "link": "https://example.com/docs/v2-migration"
        }
      }
    }
  ]
}

Response Headers

Based on the configuration above, the policy sets the following headers on the response:

• Deprecation - Set to the string "true" when input is true, an HTTP-date when input is an ISO 8601 string, or an RFC 9651 timestamp (@epoch) when input is a Unix timestamp number.
• Sunset - An HTTP-date indicating when the endpoint will be removed.
• Link - A link to deprecation documentation, formatted as <URL>; rel="deprecation"; type="text/html".

Read more about how policies work