How deeply does API Design Patterns cover deprecation?

Defines state transitions, change restrictions, removal timing, and a monthly timeline, but does not specify implementation mechanics.

Deprecation

As explained in API Design Patterns

Deprecated is the API version lifecycle state in which a former current version remains available under current-version change restrictions but is scheduled for removal.

Deprecation is the API version lifecycle state for a former current version scheduled for removal. It preserves availability while limiting changes to mandatory ones. section 24.3.2

A deprecation policy should make the transition explicit:

Promote a preview version to current when it becomes mature, leaving the existing current version as deprecated. section 24.3.2
Keep applying current-version change restrictions while the deprecated version remains available. section 24.3.2
Declare the removal interval in advance, communicate it to users, and remove the version when the interval expires. section 24.3 section 24.3.2
Treat deprecation as a forcing function for continual improvement: the strategy maintains one current version and one preview version. section 24.3.2

Monthly version cycle

With a monthly release cadence and a two-month deprecation policy, version 1 can be current in February, deprecated in March and April, and deleted in May. Meanwhile, later versions progress from preview to current. 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

Compare preview, current, deprecated, and deleted states with their allowed change policies. section 24.3.2

How API Design Patterns covers it

liveBook manning.com

Read API Design Patterns on liveBook Get the book at manning.com

Also explained in

liveBook manning.com

Django in ActionDeprecation is the practice of announcing that an existing interface or field will be removed after a transition period.
liveBook manning.com

Learn Rust in a Month of LunchesThe deprecated attribute marks a Rust item as discouraged for use and causes the compiler to issue a warning when it is used.
liveBook manning.com

Automating API DeliveryThe deprecated stability level denotes an API version that is scheduled for removal.
liveBook manning.com

Effective Platform EngineeringDeprecation is the formal designation that a feature or interface remains temporarily available but should no longer be adopted and may later be removed.

Compare how 5 books explain deprecation →

Related concepts

commentconfigured by · A comment is text or markup designated by a format's syntax as an annotation or non-content rather than ordinary executable or data content.
deleted statecontrasts with · Deleted is the API version lifecycle state in which a version has been removed and is no longer accessible.
sunset strategycontrasts with · A sunset strategy is the planned discontinuation and shutdown of a software component, such as an API or subsystem, after its supported service period.
api lifecyclepart of · An API lifecycle is the sequence of stages through which an API is designed, developed, tested, deployed, operated, evolved, and retired.
warning messageproduces · A warning message is a nonfatal diagnostic or notification about a potentially problematic, risky, unusual, or undesirable condition that may require attention.

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.