Deprecation is a formal notice that continued dependence on an HTTP resource is at risk. It discourages new usage and signals that consumers should plan migration before the resource is removed. section 4.11.3 section 4.11.2
Apply deprecation as part of an API lifecycle policy:
- Mark an operation, parameter, or schema with the OpenAPI Deprecated Boolean field. section 4.11.3
- Publish the deprecation date, support window, and migration expectations so consumers can stop starting new dependencies. section 4.11.3
- Treat sunset separately: removal makes the resource unavailable and can return 404 Not Found. section 4.11.3
- Configure breaking-change checks to distinguish planned sunsets from removals without prior deprecation. section 4.4
Deprecated endpoint with a sunset date
An API definition can mark GET /v1/catalog/categories as deprecated and record its planned removal with x-sunset: "2022-08-30". Tufin/oasdiff can then ignore the endpoint when that sunset date is past. section 4.4
Figure 4.7 API deprecation and sunset dates. After the deprecation date, an API isn’t recommended for use. But after the sunset date, the API is unavailable.
Use the timeline to distinguish the deprecation date, when use is discouraged, from the sunset date, when the API becomes unavailable. section 4.11.3
