Deprecation

When the decision has been taken to deprecate an API:

For products that are not Generally Available, the deprecation period must be at least 30 days (60 days recommended)
For Generally Available products the deprecation period must be at least 1 year
Warning emails will be sent to the API users at regular intervals before the deprecation time
A guide will be supplied to customers explaining how to migrate to the replacement API with the initial deprecation notice.
Fields and routes that are being deprecated should be marked as such in the OpenAPI spec, but not removed until the deprecation period has elapsed. This is done by setting deprecated: true on the deprecated object.
The new API must be published with the version bumped to the next version.

Discussed in #api-standards due to the messaging/workflows release.

Pre-existing standard

N/A