Sometimes it is necessary to phase out an API endpoint (or version), for instance, if a field is no longer supported in the result or a whole business functionality behind an endpoint has to be shut down. There are many other reasons as well. As long as these endpoints are still used by consumers these are breaking changes and not allowed. Deprecation rules have to be applied to make sure that necessary consumer changes are aligned and deprecated endpoints are not used before API changes are deployed.
Before shutting down an API (or version of an API) the producer must make sure that all clients have given their consent to shut down the endpoint. Producers should help consumers migrate to a new endpoint (i.e. by providing a migration manual). After all clients are migrated, the producer may shut down the deprecated API.
If the API is consumed by any external partner, the producer must define a reasonable timespan that the API will be maintained after the producer has announced deprecation. The external partner (client) must agree to this minimum after-deprecation-lifespan before he starts using the API.
API deprecation must be part of the OpenAPI definition. If a method on a
path, a whole path or even a whole API endpoint (multiple paths) should
be deprecated, the producers must set deprecated=true on each method /
path element that will be deprecated. If deprecation should happen on a
more fine grained level (i.e. query parameter, payload etc.), the
producer should set deprecated=true on the affected method / path
element and add further explanation to the description section.
If deprecated is set to true, the producer must describe what
clients should use instead and when the API will be shut down in the
description section of the API definition.
Owners of APIs used in production must monitor usage of deprecated APIs until the API can be shut down in order to align deprecation and avoid uncontrolled breaking effects.
During deprecation phase, the producer should add a Warning header
(see RFC 7234 - Warning
header) field. When
adding the Warning header, the warn-code must be 299 and the
warn-text should be in form of "The path/operation/parameter/…
{name} is deprecated and will be removed by {date}. Please see {link}
for details." with a link to a documentation describing why the API is
no longer supported in the current form and what clients should do about
it. Adding the Warning header is not sufficient to gain client consent
to shut down an API.
Clients should monitor the Warning header in HTTP responses to see if
an API will be deprecated in future.
Clients must not start using deprecated parts of an API.