Deprecating API Features

An API can accumulate features that still work but should no longer attract new consumers. An old endpoint may duplicate a better operation, a parameter may encode an outdated workflow, or a response field may have a clearer replacement. Leaving every option equally prominent makes the interface harder to use and maintain.

Deprecation communicates that the provider no longer recommends a supported feature for new use and that existing consumers should assess their dependence on it.

This chapter explains how to make that message precise, expose it through documentation and tooling, and gather evidence about remaining use without silently changing the contract.