Compose an API Deprecation Notice with Migration Timeline for Developers
Draft a developer-focused API deprecation notice with a clear timeline, migration guide, and code examples for smooth transition.
📝 The Prompt
You are a developer relations specialist at [COMPANY_NAME]. Write a clear, developer-friendly API deprecation notice for [API_NAME/ENDPOINT] that communicates the change, provides a migration path, and minimizes disruption to integrations.
Deprecation Details:
- Deprecated API/Endpoint: [DEPRECATED_ENDPOINT]
- Replacement API/Endpoint: [NEW_ENDPOINT]
- Deprecation Announcement Date: [ANNOUNCEMENT_DATE]
- Soft Deprecation Date (warnings begin): [SOFT_DEPRECATION_DATE]
- Hard Deprecation Date (endpoint removed): [HARD_DEPRECATION_DATE]
- Reason for Deprecation: [DEPRECATION_REASON]
- Affected API Versions: [AFFECTED_VERSIONS]
- Estimated Migration Effort: [EFFORT_ESTIMATE]
Structure the notice as follows:
1. **TL;DR Summary** — In 2-3 sentences, state what is being deprecated, when it will stop working, and what to use instead.
2. **Deprecation Timeline** — Present a clear visual timeline with 4-5 milestones:
- Announcement → Soft deprecation (log warnings) → Response header warnings → Hard deprecation → Full removal
Include exact dates for each milestone.
3. **What's Changing and Why** — Explain the technical rationale in 3-4 sentences. Focus on how the new API is better (performance, security, functionality).
4. **Migration Guide** — Provide a side-by-side comparison table showing:
- Old endpoint vs. new endpoint
- Old request format vs. new request format
- Old response schema vs. new response schema
- Authentication changes (if any)
Include 2-3 concrete code examples in [PROGRAMMING_LANGUAGE] showing before and after.
5. **Breaking Changes Checklist** — List every breaking change as a bullet point with the specific action required.
6. **Support & Resources** — Link to [MIGRATION_DOCS_URL], [CHANGELOG_URL], and [DEVELOPER_SUPPORT_EMAIL]. Mention office hours or migration support sessions if available at [SUPPORT_SCHEDULE].
7. **Feedback Channel** — Invite developers to share concerns or request deadline extensions via [FEEDBACK_CHANNEL].
Tone: Direct, technically accurate, respectful of developers' time. No marketing fluff.
💡 Tips for Better Results
Give developers at least 6-12 months between announcement and hard deprecation for production APIs. Include deprecation warnings in API response headers before the cutoff so automated monitoring catches it. Offer a dedicated Slack channel or forum thread where developers can ask migration questions and share solutions with each other.
🎯 Use Cases
Developer relations teams, API product managers, and technical support leads use this when sunsetting an API version or endpoint to ensure partners and developers migrate smoothly with minimal integration breakage.