An API deprecation policy template

A deprecation policy is a promise to your API consumers: how much warning they get before something they depend on goes away. Publish it before you need it, and every retirement after that is a policy being followed, not a negotiation.

Below is a template you can copy, then notes on each choice it asks you to make.

The template

Replace everything in square brackets. Delete any section that doesn't apply to you.

# [Company] API deprecation policy

Last updated: [date]

## What this covers
This policy applies to every endpoint, field, parameter and version of the
[Company] API documented at [docs URL]. It does not cover [beta / preview /
internal] endpoints, which may change without notice.

## Definitions
- Deprecated: still works and is still supported, but has a replacement and
  will be retired. Don't build anything new on it.
- Retired (sunset): no longer available. Requests return 410 Gone.

## Notice
- We give at least [6 months] between announcing a deprecation and retiring it.
- Breaking changes to a current version are never made without a new version.
- Security fixes may shorten this window. If they do, we will contact every
  affected client directly.

## How we tell you
- Every response from a deprecated endpoint carries a Deprecation header
  (RFC 9745) and, once the date is set, a Sunset header (RFC 8594).
- We email the technical contact on each affected account when a deprecation
  is announced, and again [30, 7 and 1] days before the retirement date.
- Deprecations are listed in the changelog at [changelog URL].

## Support for deprecated versions
- Deprecated versions receive [security fixes only / security and critical
  bug fixes] until they are retired.
- No new features are added to deprecated versions.

## Extensions
- If you need more time, contact [email] before the retirement date.
- [Role, e.g. the API product owner] may grant an extension of up to
  [90 days], once per client.

## After retirement
- Requests to a retired endpoint return 410 Gone, with a link to the
  migration guide.
- Retired endpoints are not brought back.

Choosing the notice period

The notice period is the decision that matters most. Too short and consumers can't plan the work. Too long and old versions pile up.

• 6 months is a common default for public and partner APIs. It covers one planning cycle for most teams.
• 12 months suits APIs that large enterprises or mobile apps depend on, where releases are slow.
• 30 to 90 days can work for internal APIs, where you know every caller by name.

Whatever you choose, make it a minimum, not a fixed date. You can always give more notice.

What people forget to include

• What counts as breaking. Say whether adding a field, adding an enum value, or tightening validation counts. Consumers with strict parsers will ask.
• Who to contact. A real address that someone reads, not a generic support queue.
• The exception process. Someone will ask for more time. Deciding who can say yes before it happens keeps the answer consistent.
• Where it lives. Link the policy from your docs home page and from the Link header on every deprecated response.

Where EndPointBlank fits

A policy is only as good as the evidence behind it. EndPointBlank shows which clients still call each deprecated version, sends the Deprecation and Sunset headers from your client library with no code, and reminds affected clients 30, 7 and 1 day before the date. The policy above describes what it does.

See how version lifecycle works or start free. When it's time to retire something, follow how to deprecate an API version.