How to Write an API Deprecation Notice in English

An API deprecation notice that’s vague about dates causes exactly the problem it’s supposed to prevent — developers either panic and migrate too early, or ignore it and get broken in production, because the notice didn’t give them a concrete enough timeline to plan around.

Key Vocabulary

Deprecation date — the date from which an API endpoint or feature is officially marked deprecated, meaning it still works but is no longer recommended and won’t receive further updates, distinct from the later date it stops working entirely. “The deprecation date is July 1st — from that point, the endpoint still works exactly as before, but it’s marked deprecated in our docs and won’t receive bug fixes or new features going forward. That’s different from when it actually stops working.”

Sunset date — the explicit future date the deprecated API will actually stop functioning, given with enough advance notice for consumers to migrate, and stated as a hard, non-negotiable deadline rather than an approximate window. “The sunset date is January 1st of next year — six months from the deprecation date. After that date, calls to this endpoint will return a 410 Gone response. This is a hard date, not an estimate, so please plan your migration around it.”

Migration path — the concrete replacement API or approach, including specific code examples, that consumers should switch to, provided directly in the deprecation notice rather than requiring them to search documentation separately. “Migration path: replace calls to GET /v1/users/:id with GET /v2/users/:id. The response shape is mostly the same, except the name field is now split into firstName and lastName — see the example below for the exact before-and-after.”

Breaking vs. non-breaking — classifying whether the deprecated API’s replacement requires code changes on the consumer’s part, which determines how urgently and prominently the notice needs to be communicated. “This is a breaking change, not a non-breaking one — the response shape genuinely changes, so every consumer needs to update their parsing code. That’s why we’re giving six months’ notice and sending direct emails, not just a changelog entry.”

Common Phrases

• “What’s the deprecation date, and separately, what’s the actual sunset date?”
• “Is there a clear migration path with a code example, or just a general description?”
• “Is this breaking or non-breaking for existing consumers?”
• “Have affected users been notified directly, not just through a changelog entry?”
• “Is the sunset date far enough out to give consumers reasonable time to migrate?”

Example Sentences

Stating both dates clearly: “Deprecation notice: the /v1/search endpoint is deprecated as of March 1st, 2027. It will continue to function until its sunset date of September 1st, 2027, six months later, after which requests to it will return a 404.”

Providing a concrete migration path: “Migration path: replace /v1/search?q=term with /v2/search?query=term. Note the parameter name change from q to query. The response format is otherwise identical, so most consumers will only need to update the request, not their response parsing.”

Classifying the impact honestly: “This is a breaking change for any consumer relying on the old pagination format — the new endpoint uses cursor-based pagination instead of offset-based, so pagination logic will need to be rewritten, not just the endpoint URL updated.”

Professional Tips

• State the deprecation date and sunset date as two distinct, explicit dates, never conflated into one vague notice — consumers need to know both when support ends and when functionality actually stops.
• Always include a concrete migration path with a before-and-after code example directly in the notice — making developers hunt through separate documentation increases the chance they miss it or migrate incorrectly.
• Classify the change as breaking vs. non-breaking honestly and prominently — understating the impact of a breaking change is what causes consumers to be caught off guard in production.
• Give a sunset date far enough in the future to be realistic for consumers to migrate, and communicate directly to known API consumers, not just through a changelog entry nobody reads.

Practice Exercise

1. Write a deprecation notice stating both a deprecation date and a sunset date clearly.
2. Draft a migration path section with a before-and-after code example.
3. Write a sentence classifying a hypothetical API change as breaking or non-breaking, and explain why.