# Deprecate an API endpoint with a migration guide

Plans the deprecation of an API endpoint or field and writes the timeline, announcement, and migration guide for its consumers.

- Topic: Software Development
- Framework: RTF
- Level: Standard
- Tags: Coding, Communication, Plan, Fill-in Template
- Source: https://www.thinkwithprompt.com/prompts/deprecate-an-api-endpoint-with-a-migration-guide

## Prompt

```text
Help me deprecate part of an API without breaking the people who depend on it.

**What's being deprecated:** [ENDPOINT, FIELD, SDK METHOD, OR VERSION]
**Replacement:** [NEW ENDPOINT OR BEHAVIOR, WITH EXAMPLE REQUEST AND RESPONSE]
**Why:** [REASON IN USER TERMS]
**Who uses it:** [INTERNAL TEAMS / EXTERNAL CUSTOMERS / PUBLIC DEVELOPERS - and usage data if known]
**Constraints:** [CONTRACTUAL NOTICE PERIODS, MOBILE APPS THAT CAN'T FORCE UPGRADES, VERSIONING POLICY]

Produce:
1. **Timeline:** announce, deprecation warnings live, brownouts (optional, short planned outages to surface remaining callers), sunset date. Justify the length based on who the consumers are; use [CONFIRM NOTICE PERIOD] for anything contractual.
2. **Technical signals:** deprecation headers or response warnings, logs to identify remaining callers, docs changes, and SDK warnings.
3. **Migration guide:** what's changing, before/after code examples, field-by-field mapping, behavior differences and edge cases, and an FAQ.
4. **Announcement:** a short message for a changelog, email, or developer forum, plus a reminder message for 30 days and 7 days before sunset.
5. **Tracking:** how to measure remaining usage and who to contact directly when sunset nears.
6. **Rollback:** what we do if a critical consumer can't migrate in time.

Don't invent current usage numbers; mark them [ADD USAGE DATA].
```

## What to fill in

- ENDPOINT, FIELD, SDK METHOD, OR VERSION
- NEW ENDPOINT OR BEHAVIOR, WITH EXAMPLE REQUEST AND RESPONSE
- REASON IN USER TERMS
- CONFIRM NOTICE PERIOD
- ADD USAGE DATA

Free to copy and use. From ThinkWithPrompt (https://www.thinkwithprompt.com/), a library of 2,663 curated AI prompts.