The API Deprecation Notice Drafter: Turn a Breaking Change Into a Migration Plan Nobody Ignores
Why this prompt matters
Badly communicated API deprecations are one of the most avoidable causes of production incidents. A vague notice with no before/after examples means every downstream team re-derives the migration independently, often incorrectly, right up until the cutover breaks their service. The engineer who skips the migration guide ends up answering the same five questions in DMs for three weeks and then firefighting a wave of errors on cutover day anyway — exactly the outcome this prompt is built to prevent.
What we use it for
You're a platform engineer at a mid-size SaaS company. Your team is retiring the v1 /users endpoint in favor of v2 because v1 leaks partial SSNs in its error responses — a problem flagged in a recent security review. 23 internal services and 6 external API partners still call v1. You have a hard compliance deadline to complete the migration, and before your standup in an hour you need the full communication package ready: the notice, the migration guide, the timeline, and the announcement.
Prompt
Act as a senior platform engineer and technical writer who has shipped dozens of API deprecations without breaking downstream consumers. CONTEXT: I'm deprecating [API/ENDPOINT NAME] because [REASON FOR DEPRECATION]. It is currently used by approximately [NUMBER] of consumers / teams, including [KEY CONSUMER TEAMS OR PARTNERS]. The replacement is [REPLACEMENT API/ENDPOINT OR APPROACH]. The hard cutoff date is [CUTOFF DATE], with a target migration window starting [MIGRATION START DATE]. Known behavioral differences between the old and new API: [LIST KEY DIFFERENCES, E.G. FIELD RENAMES, RATE LIMIT CHANGES, AUTH CHANGES]. TASK: Produce a complete deprecation communication package: 1. A changelog-style deprecation notice (2-3 sentences, technical, precise) 2. A migration guide section with before/after code or request examples for the top 3 most common usage patterns 3. A risk-tiered rollout timeline (warning period, grace period, hard cutoff) with specific dates 4. A one-paragraph Slack/email announcement for downstream team leads that states the ask, the deadline, and where to get help 5. Three FAQ entries anticipating the most likely pushback or confusion points CONSTRAINTS: - Do not use vague timing language like "soon" or "in the coming weeks" — every deadline must be a specific date or relative to [CUTOFF DATE] - Do not bury the breaking change — state what will stop working and when in the first two sentences of the notice - Assume the reader is a competent engineer who is busy and will skim — front-load the action they need to take - If [NUMBER] of consumers is large (50+), include a note recommending a phased rollout rather than a single cutover - Keep the Slack/email announcement under 150 words OUTPUT FORMAT: ## Deprecation Notice [changelog text] ## Migration Guide ### Pattern 1: [name] **Before:** [code/request] **After:** [code/request] (repeat for patterns 2 and 3) ## Rollout Timeline | Phase | Dates | What Happens | |---|---|---| ## Announcement Draft [the Slack/email text] ## Anticipated FAQ **Q:** ... **A:** ...
Result
Deprecation Notice
The /v1/users endpoint is deprecated effective December 1, 2026, and will stop accepting requests entirely on January 15, 2027. All consumers must migrate to /v2/users, which removes the PII leakage present in v1's 4xx error responses and adds cursor-based pagination. No new features will be added to v1 during the transition window.
Migration Guide
Pattern 1: Fetching a single user by ID
Before: GET /v1/users/{id} returns { "id": "...", "email": "...", "ssn_last4": "..." }
After: GET /v2/users/{id} returns { "id": "...", "email": "...", "tax_id_last4": "..." }
Note: ssn_last4 is renamed to tax_id_last4 and is now redacted unless the caller holds the pii:read scope.
Pattern 2: Listing users with pagination
Before: GET /v1/users?page=2&limit=50
After: GET /v2/users?cursor=eyJpZCI6MTIzfQ&limit=50
Page-number pagination is removed. Store the next_cursor field from each response instead of calculating page numbers.
Pattern 3: Error responses on invalid auth
Before: v1 returns the full user object in 403 error bodies (the PII leak driving this deprecation).
After: v2 returns { "error": "forbidden", "code": "AUTH_SCOPE_MISSING" } with no user data.
Rollout Timeline
Warning (Nov 4 - Dec 1, 2026): v1 fully functional; deprecation headers added to all v1 responses.
Grace (Dec 1, 2026 - Jan 14, 2027): v1 functional but rate-limited to 10% of normal quota to force migration testing.
Hard cutoff (Jan 15, 2027): v1 returns 410 Gone on all requests.
Announcement Draft
Hi teams — we're retiring /v1/users starting today. Reason: v1's error responses leak partial SSNs, flagged in last week's security review. /v2/users is live now and fixes this, with one breaking change: page-number pagination is replaced by cursors. Full before/after examples are in the migration guide (linked). Hard cutoff is January 15 — after that, v1 returns errors on every call. If you're one of the 23 internal services or 6 partner integrations on v1, reply here or ping #platform-migrations by November 18 so we can track who's done.
Anticipated FAQ
Q: Can we get an extension past January 15?
A: Only with a documented compliance exception from Security — the PII leak is the reason for the deadline, not an arbitrary target.
Q: Will ssn_last4 still work if we don't request the new scope?
A: No — the field is renamed and scope-gated. Calls without pii:read will simply omit it, not error.
Q: Do external partners get a longer window?
A: No, the hard cutoff is the same for everyone, but partners get a dedicated Slack channel and a named contact for migration support.
Every API deprecation follows the same failure pattern: an engineer announces a cutoff date in a Slack message, three teams acknowledge it, and six weeks later the actual migration happens in a panic the week before the hard deadline — because nobody wrote down the specific field renames, pagination changes, or error-format differences until someone's production service broke.
This prompt is built around five mandatory deliverables, not because more output is better, but because each one closes a specific failure mode. The changelog-style notice forces precision on dates — no "soon," no "coming weeks" — because vague timing is the single biggest reason deprecations get ignored until the last minute. The migration guide demands before/after examples for the three most common usage patterns, since most teams don't read prose documentation; they copy-paste the closest matching example and adapt it. If that example doesn't exist, they guess, and guessing is where production incidents start.
The risk-tiered rollout timeline — warning, grace, hard cutoff — exists because a single cutover date gives engineering teams no way to test migration under real load before it's irreversible. A grace period with reduced quota (10% of normal traffic, in the example) forces teams to actually exercise the new endpoint instead of deferring until the deadline.
The constraint that bans vague timing language is deliberate: it's the most commonly violated rule in real deprecation notices, and the one most responsible for teams treating a hard deadline as a soft suggestion. The constraint capping the Slack/email announcement at 150 words exists because deprecation announcements compete with dozens of other Slack messages for attention — a long announcement gets skimmed and forgotten, a short one with a clear deadline gets acted on.
The anticipated FAQ section is the part most engineers skip when writing these themselves, and it's the part that saves the most time afterward. Three pre-answered questions in the original announcement prevent the same three questions arriving individually in DMs from twenty different engineers over the following weeks.
Use this when you're the one retiring an endpoint, not just renaming a field — anything with a hard cutoff date and more than a handful of downstream consumers benefits from having the communication fully drafted before the first Slack message goes out.