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.

Navigating Nuances: Language Considerations for Non-Native Speakers

Writing a clear and effective API deprecation notice isn’t just about stating facts; it’s about conveying information in a way that minimizes confusion and maximizes collaboration. For developers whose first language isn’t English, the subtleties of professional phrasing can be particularly challenging. It’s easy to unintentionally sound abrupt or unclear when using idioms and common expressions. Let’s consider some specific areas where careful attention can make a significant difference.

Firstly, temporal language is often tricky. Phrases like “in the near future,” “shortly,” or “within the next few months” are loaded with implied timelines that may not be immediately obvious to someone accustomed to different ways of expressing time. Instead of relying on vague terms, strive for precision. Saying “This endpoint will be removed on December 31st, 2024” is far more effective than “We’ll let you know soon.” Consider adding a detailed timeline: “Phase 1 – Warning messages will appear in the API from July 1st, 2024. Phase 2 – The endpoint will no longer accept requests starting January 1st, 2025.” This layered approach provides clarity and reduces ambiguity around the actual impact.

Secondly, the concept of “migration paths” needs careful explanation. Simply stating “migrate to Endpoint B” isn’t sufficient. You need to provide direction. For example, instead of saying “Please migrate your code to Endpoint B,” try, “To continue using this functionality, you’ll need to update your application to utilize the new Endpoint B, which offers improved performance and security features. We’ve documented the migration process here: [link to documentation].” Using active voice – “you’ll need to” – is generally clearer than passive constructions like “the code should be migrated.”

Finally, remember that API deprecation notices are inherently about change. Framing this change positively, while acknowledging its impact, can foster a more collaborative environment. Instead of focusing solely on what’s being removed, highlight the benefits of the new approach: “As we evolve our platform to enhance stability and performance, we’re retiring Endpoint A. This transition allows us to introduce [new feature] and optimize overall system efficiency.” Phrases like “transitioning to” or “shifting towards” can soften the impact of the deprecation and signal a proactive rather than reactive approach.