liveBook · Manning

Deprecation policy

As explained in API Design Patterns

A deprecation policy is a set of rules specifying how long deprecated API versions remain available and when they are expected to stop working.

A deprecation policy specifies how long an old API version remains available and when it will stop working. Declare the timeline before release and communicate it to users. section 24.3 section 24.3.2

Choose the policy by balancing compatibility against operational complexity:

  • Keeping versions indefinitely maximizes stability but can require maintaining every historical version. section 24.3 section 24.3.3
  • Removing versions after a declared interval limits active-version overhead but forces users to update before the deadline. section 24.4.1 section 24.3.2
  • A practical middle ground keeps a reasonable number of versions while matching users’ stability requirements and the provider’s management capacity. section 24.4.1

A two-month release cycle

With monthly releases and a two-month deprecation policy, version 1 can be previewed in January, become current in February, become deprecated in March, and be deleted in May. Version 2 follows the same progression while newer versions move through preview and current states. section 24.3.2

Table 24.1 Overview of different version states (view table figure)

State

Description

Change policy

Preview

An unstable and still-in-progress preview of functionality users should expect to exist in the next current version

All changes permitted

Current

A very stable set of functionality that should not change and can be expected to continue running for some pre-decided amount of time

Only mandatory changes

Deprecated

A prior current version that is scheduled for impending removal according to the deprecation policy

Only mandatory changes

Deleted

A prior deprecated version that has been removed or otherwise made inaccessible to users

N/A

Use the version-state table to distinguish preview, current, deprecated, and deleted versions, including the changes permitted in each state. section 24.3.2

How API Design Patterns covers it

How deep it goes
Compares indefinite retention with timed removal and explains declared timelines, but does not prescribe one universal duration.
Examples
Uses a monthly-release timeline in which versions progress from preview to current, deprecated, and deleted.
What it assumes
Assumes familiarity with API versions and backward-incompatible changes while clarifying how their retirement should be managed.
What you can do after
Operate/configure an API lifecycle by declaring maintenance periods, communicating deadlines, and removing expired versions.
How it connects
Connects API versioning, backward compatibility, semantic versioning, and agile instability with current, deprecated, and deleted states.
Cover of API Design Patterns
liveBookmanning.com
Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.