API Deprecation Policy Design Prompt

This prompt is for API product owners, platform architects, and engineering leads who need to design a complete deprecation lifecycle for a public, partner, or internal API. The job-to-be-done is producing a policy document that covers announcement timelines, Sunset headers, migration windows, consumer communication templates, and exception criteria—before any endpoint is actually deprecated. The ideal user brings the API's current versioning scheme, a list of active consumers (or consumer personas), and the organization's existing change management or SLA commitments. Without these inputs, the prompt produces a generic policy that won't survive contact with real consumers.

Use this prompt when you are formalizing a deprecation process for the first time, auditing an existing policy against industry practices, or preparing a deprecation plan for a specific API version. The prompt is designed to produce a structured policy with concrete timeframes, not a one-off deprecation notice. It assumes you control the API surface and can enforce the policy. Do not use this prompt when you need a consumer-facing deprecation email for a single endpoint (use a communication template instead), when you are deprecating an internal library with no network boundary, or when the API is governed by an external regulatory body with fixed retirement rules that override organizational policy. The prompt also should not be used to decide whether to deprecate—it assumes the decision has already been made and focuses on how to execute it safely.

The output is a policy document, not a legal agreement. It should be reviewed by legal, developer relations, and the teams that own affected consumers before publication. The prompt includes completeness checks against common industry practices (Google's Deprecation Policy, Microsoft's Breaking Changes Policy, and the IETF Deprecation header RFC draft), but it does not guarantee compliance with any specific regulation. If your API serves healthcare, financial, or critical infrastructure consumers, add a mandatory human review gate after policy generation and before any deprecation announcement is sent.

The following prompt template is designed to produce a structured API deprecation policy document. It guides the model through the essential components of a deprecation lifecycle: announcement timelines, Sunset headers, migration windows, consumer communication templates, and completeness checks against industry practices. Use the square-bracket placeholders to inject your specific API context, organizational constraints, and output format requirements before sending the prompt to the model.

textCopy
You are an API governance architect designing a deprecation policy for a production API surface. Your task is to produce a complete, actionable deprecation policy document that covers the full lifecycle from announcement to sunset.

## API CONTEXT
- API Name: [API_NAME]
- API Version(s) affected: [AFFECTED_VERSIONS]
- Current consumer profile: [CONSUMER_PROFILE]
- Regulatory or compliance requirements: [COMPLIANCE_REQUIREMENTS]
- Organizational risk tolerance: [RISK_TOLERANCE]

## POLICY REQUIREMENTS
Generate a deprecation policy that includes the following sections. For each section, provide concrete rules, timelines, and templates, not abstract guidance.

### 1. Deprecation Classification
Define at least three severity levels for deprecation (e.g., minor, major, critical) with clear criteria for each. Include examples of changes that fall into each level.

### 2. Announcement Timeline
For each severity level, specify the minimum notice period before the deprecation takes effect. Include milestones for initial announcement, reminder, and final warning. Express timelines in calendar days or months, not vague terms like "reasonable notice."

### 3. Sunset Header Specification
Define the exact HTTP header format for signaling deprecation and sunset dates. Include the header name, value format, and behavior expectations. Reference RFC 8594 (Sunset header) and explain any extensions or deviations.

### 4. Migration Window
For each severity level, specify the duration of the migration window during which both old and new versions are available. Define what happens when the migration window closes.

### 5. Consumer Communication Templates
Provide ready-to-use templates for:
- Initial deprecation announcement (email or dashboard notification)
- Reminder notification
- Final sunset warning
- Post-sunset confirmation
Each template must include placeholders for dates, affected endpoints, migration instructions, and support contact information.

### 6. Monitoring and Enforcement
Define how the organization will track deprecated endpoint usage, identify non-migrated consumers, and enforce sunset dates. Include metrics to monitor and escalation paths for consumers who fail to migrate.

### 7. Exception Process
Define the process for granting exceptions to the standard deprecation timeline. Include who can approve exceptions, maximum extension duration, and documentation requirements.

### 8. Completeness Checklist
Include a checklist that API owners must complete before initiating a deprecation. Cover items such as: migration guide published, consumer impact analysis completed, support team briefed, monitoring dashboards configured, and legal/compliance review completed.

## OUTPUT FORMAT
[OUTPUT_SCHEMA]

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
For reference, here are examples of well-structured deprecation policies from industry:
[EXAMPLES]

To adapt this template, replace each placeholder with concrete values. The [API_NAME] and [AFFECTED_VERSIONS] fields ground the policy in your specific API surface. The [CONSUMER_PROFILE] field should describe whether your consumers are internal teams, external partners, or public developers, as this shapes communication tone and migration support expectations. The [COMPLIANCE_REQUIREMENTS] and [RISK_TOLERANCE] fields are critical for regulated industries where deprecation timelines may be constrained by contractual obligations or regulatory mandates.

The [OUTPUT_SCHEMA] placeholder should specify the desired output format, such as "Markdown document with H2 section headings" or "JSON object with section keys and content values." The [CONSTRAINTS] placeholder can include rules like "Do not recommend timelines shorter than 90 days for external consumers" or "All communication templates must include a support escalation path." The [EXAMPLES] placeholder is optional but strongly recommended; include excerpts from well-known API deprecation policies such as those from Stripe, GitHub, or AWS to anchor the model's output in proven industry patterns.

Before using this prompt in production, validate the generated policy against your organization's existing change management processes. The model may produce timelines that conflict with your contractual obligations or communication templates that don't align with your brand voice. Always review the output with your API governance team and legal counsel before publishing. For high-risk deprecations affecting paying customers or regulated data, require human approval on the final policy document and all consumer-facing communications.

This prompt is designed to be called from an API governance or developer portal backend, not as a one-off chat interaction. The primary integration point is a policy generation endpoint that accepts structured inputs—API name, current version, target deprecation date, migration guide URL, and consumer contact list—and returns a complete deprecation policy document. The prompt should be treated as a draft generator, not a publisher. Every generated policy must pass through a human review gate before being committed to a public changelog, emailed to consumers, or applied as an HTTP Sunset header.

Wire the prompt into an application pipeline with these stages: (1) Input validation—reject requests missing required fields ([API_NAME], [DEPRECATION_DATE], [SUNSET_DATE], [MIGRATION_GUIDE_URL]). Validate that dates are in the future and that SUNSET_DATE is at least 90 days after DEPRECATION_DATE unless a shorter window is explicitly justified. (2) Prompt assembly—inject validated fields into the template, along with any [CONSUMER_CONTEXT] (active client counts, SLA tiers, internal vs. external consumers). (3) Model call—use a model with strong instruction-following and structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature=0.2 for consistency. (4) Output validation—parse the generated policy and run automated checks: confirm the Sunset header format is RFC 8594-compliant, verify all required sections are present (announcement, timeline, migration path, communication templates, FAQ), and check that no placeholder tokens remain in the output. (5) Human review queue—route validated drafts to the API product owner for approval. The review UI should highlight dates, URLs, and consumer-facing language for quick scanning. (6) Publication triggers—on approval, push the policy to your developer portal, schedule email notifications to registered consumers, and configure the API gateway to begin serving the Sunset and Deprecation HTTP headers on the deprecated endpoints.

For teams using OpenAPI specifications as the source of truth, extend the harness to read the deprecated endpoint list directly from the spec file. Parse deprecated: true annotations and endpoint paths, then feed them into the prompt as [DEPRECATED_ENDPOINTS]. This prevents drift between the spec and the policy document. For high-traffic APIs with many consumers, add a staged rollout step: generate the policy, publish it to a staging developer portal, monitor consumer questions for one week, then iterate on the FAQ section before broad distribution. Avoid wiring this prompt directly to an automated publication pipeline without human review—deprecation miscommunication causes production incidents and erodes consumer trust.