Deprecation Header Injection Prompt for API Responses

This prompt is for API platform engineers who need to generate machine-readable HTTP deprecation headers and human-readable warning bodies for API responses. Use it when you have a defined deprecation schedule and need to inject consistent, standards-compliant deprecation signals into your API gateway, middleware, or response pipeline. The prompt produces a complete header configuration object and a structured warning body that downstream clients and API consumers can parse programmatically.

The ideal user has access to the deprecation schedule, the sunset date, the replacement endpoint URI, and the API's documentation link. Required context includes the deprecated resource path, the RFC 8594 sunset date, and any migration documentation URL. The prompt expects these as explicit inputs and will not invent dates or replacement endpoints. It enforces strict compliance with the Sunset and Deprecation HTTP header field specifications, ensuring that the Sunset header uses an HTTP-date format and the Deprecation header is set to true.

Do not use this prompt to draft customer-facing email announcements, blog posts, or status page updates. It is strictly for HTTP response-level injection. The output is a machine-actionable configuration object, not a marketing message. If you need to communicate the deprecation to humans through channels other than the API response itself, use a sibling prompt such as the API Deprecation Notice Drafting Prompt Template or the Multi-Channel Sunset Announcement Prompt. After generating the header configuration, validate it against your OpenAPI specification and test it in a staging environment before deploying to production.

This prompt template generates the exact Sunset, Deprecation, and Link HTTP header values plus a structured response body warning that your API gateway or middleware should inject into deprecated endpoint responses. The template is designed to be wired into a configuration generation pipeline, CI/CD step, or internal tooling where you need machine-readable deprecation signals that downstream clients can parse programmatically. Before using this template, ensure you have the deprecation schedule, replacement endpoint URLs, migration guide links, and sunset date confirmed in your deprecation policy. This prompt is not a substitute for customer-facing deprecation emails or developer portal announcements—it handles the in-band HTTP signaling layer only.

textCopy
You are an API deprecation configuration generator. Your output will be consumed by an API gateway configuration system. Generate strictly valid, machine-readable deprecation signals for an HTTP endpoint.

## INPUT
- Endpoint path: [ENDPOINT_PATH]
- HTTP method: [HTTP_METHOD]
- Sunset date (RFC 7231 HTTP-date format): [SUNSET_DATE]
- Deprecation date (RFC 7231 HTTP-date format): [DEPRECATION_DATE]
- Replacement endpoint URL (full URI or relative path): [REPLACEMENT_URL]
- Migration guide URL: [MIGRATION_GUIDE_URL]
- Deprecation scope (e.g., "full endpoint", "specific query parameter", "response field"): [DEPRECATION_SCOPE]
- Current API version: [CURRENT_VERSION]
- Version where endpoint will be removed: [REMOVAL_VERSION]
- Contact email for questions: [CONTACT_EMAIL]

## CONSTRAINTS
- Headers must comply with RFC 8594 (Sunset) and the Deprecation HTTP header field draft.
- The Sunset header value must be an HTTP-date as defined in RFC 7231, section 7.1.1.1.
- The Deprecation header value must be an HTTP-date indicating when the deprecation was announced.
- The Link header must use the `rel="deprecation"` relation type pointing to the migration guide.
- The response body warning must be a JSON object with a structured `warning` field, not free text.
- Do not include speculative dates, placeholder values, or commentary outside the output format.
- If any required input is missing, output a JSON error object with `"error": true` and a `"missing_fields"` array.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "headers": {
    "Sunset": "<HTTP-date>",
    "Deprecation": "<HTTP-date>",
    "Link": "<[REPLACEMENT_URL]>; rel=\"alternate\", <[MIGRATION_GUIDE_URL]>; rel=\"deprecation\""
  },
  "response_body": {
    "warning": {
      "type": "deprecation",
      "scope": "[DEPRECATION_SCOPE]",
      "sunset_date": "[SUNSET_DATE]",
      "removal_version": "[REMOVAL_VERSION]",
      "replacement_url": "[REPLACEMENT_URL]",
      "migration_guide": "[MIGRATION_GUIDE_URL]",
      "contact": "[CONTACT_EMAIL]"
    }
  }
}

## VALIDATION RULES
- Sunset date must be in the future relative to the deprecation date.
- Deprecation date must be in the past or present (announcement already occurred).
- Replacement URL must be a valid URI or start with "/".
- Contact email must contain an "@" character.

## EXAMPLES
Input: GET /v1/users, Sunset: Tue, 01 Jul 2025 00:00:00 GMT, Deprecation: Tue, 01 Jan 2025 00:00:00 GMT, Replacement: /v2/users, Migration: https://docs.example.com/migrate-users, Scope: full endpoint, Current: v1, Removal: v2, Contact: api-support@example.com
Output:
{
  "headers": {
    "Sunset": "Tue, 01 Jul 2025 00:00:00 GMT",
    "Deprecation": "Tue, 01 Jan 2025 00:00:00 GMT",
    "Link": "</v2/users>; rel=\"alternate\", <https://docs.example.com/migrate-users>; rel=\"deprecation\""
  },
  "response_body": {
    "warning": {
      "type": "deprecation",
      "scope": "full endpoint",
      "sunset_date": "Tue, 01 Jul 2025 00:00:00 GMT",
      "removal_version": "v2",
      "replacement_url": "/v2/users",
      "migration_guide": "https://docs.example.com/migrate-users",
      "contact": "api-support@example.com"
    }
  }
}

## OUTPUT
Generate the deprecation configuration for the provided inputs. Return only the JSON object, no markdown fences or commentary.

To adapt this template for your environment, replace every square-bracket placeholder with values sourced from your deprecation tracking system or API governance registry. The SUNSET_DATE and DEPRECATION_DATE must be valid HTTP-date strings—use a date library in your pipeline to format these rather than relying on the model to generate them from natural language. The Link header construction follows RFC 8288; if your replacement endpoint has multiple alternates, extend the Link value with additional rel="alternate" entries before the rel="deprecation" entry. For endpoints deprecated at the field level rather than the full endpoint, set DEPRECATION_SCOPE to something like response field "legacy_id" and adjust the response body warning accordingly. If your API gateway requires headers in a specific configuration format (e.g., Envoy, Kong, or AWS API Gateway), add a post-processing step that maps this JSON output into the gateway's configuration schema—this prompt produces the canonical values, not the gateway-specific wiring.

Before deploying generated configurations, validate the output against your deprecation schedule in a staging environment. Run an integration test that calls the deprecated endpoint and asserts that all three headers are present with correct values, that the response body contains the structured warning, and that the Sunset date matches the published timeline. If your deprecation policy requires a Warning header with a 299 warn-code in addition to the Sunset header, extend the output schema and prompt constraints accordingly. Never deploy deprecation headers to production without confirming that the sunset date has been reviewed by the API product manager and that the replacement endpoint is live and documented.

This prompt is designed to be called programmatically from your API gateway, reverse proxy, or response middleware, not manually. The model receives a structured request containing the endpoint path, HTTP method, current deprecation schedule, and the desired output format. Its response must be parsed as a strict JSON object containing the header names and values to inject. Do not treat this as a conversational prompt; it is a machine-to-machine instruction that must produce deterministic, validatable output every time.

Before injecting any header, validate the Sunset field against the HTTP-date specification (RFC 7231, Section 7.1.1.1) using a regex such as ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$. Reject any output where the date does not match the published deprecation schedule for that endpoint version. If validation fails, retry the prompt once with an additional [CONSTRAINTS] block that explicitly lists the allowed sunset dates per endpoint. After a second failure, log the error, alert the on-call channel, and fall back to a static header configuration defined in your infrastructure-as-code repo.

Log every injection event—including the endpoint, injected header names and values, model version, and a timestamp—to your structured logging system (e.g., structured JSON to stdout, shipped to your observability platform). This audit trail is critical for debugging consumer-reported issues and proving compliance with your published deprecation policy. For high-traffic APIs, cache the generated header configuration per endpoint version in your gateway's in-memory store (e.g., a TTL-based cache keyed by endpoint:version) and refresh only when the deprecation schedule changes. Do not inject headers on endpoints not listed in the deprecation schedule; the middleware should check the endpoint against the schedule before calling the model. Human review is required before enabling deprecation headers in production for the first time on a new endpoint—use a feature flag or a manual approval step in your deployment pipeline to gate this.