Deprecation
When the decision has been taken to deprecate an API:
- Set an appropriate deprecation time period:
- 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
- Mark the deprecations:
- 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: trueon the deprecated object. - The routes should return a
Deprectationwith a datetime the deprecation began, and aSunsetheader with a datetime of the sunset date.
- 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
- Alert affected customers:
- 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.
- The new API must be published with the version bumped to the next version.
Why did we choose this?
Beta
Discussed in #api-standards due to the messaging/workflows release.
Non-Beta
Pre-existing standard