At a glance#
A client learns that an operation is going away from the specification and from the response itself. The specification marks the operation deprecated: true; every success response of that operation documents two headers.
| Header | Standard | Value | Example |
|---|---|---|---|
Deprecation | RFC 9745 | The moment the operation was deprecated, as a Unix timestamp with a leading @ | Deprecation: @1792368000 |
Sunset | RFC 8594 | The moment the operation stops answering, as an HTTP date | Sunset: Tue, 19 Jan 2027 00:00:00 GMT |
Link | RFC 8288 | Optional: the replacement, with rel="successor-version" | Link: </v3/orders>; rel="successor-version" |
HTTP/1.1 200 OK Deprecation: @1792368000 Sunset: Tue, 19 Jan 2027 00:00:00 GMT Link: </v3/orders>; rel="successor-version" Content-Type: application/json
In the specification#
/orders/legacy:
get:
operationId: legacyOrders
deprecated: true
description: Replaced by the orders list of v3.
responses:
"200":
description: Orders.
headers:
Deprecation:
description: When this operation was deprecated.
schema: { type: string }
Sunset:
description: When this operation stops answering.
schema: { type: string }Say in the description what replaces the operation. The Sunset moment is never earlier than the end of the notice period of the versioning rules.
Planned
The gateway adds the Deprecation and Sunset headers to every response of a deprecated major version, and the routes stay in place until the sunset date.
Checked by#
| Rule | Severity | Checks |
|---|---|---|
api360-deprecation-headers | error | An operation with deprecated: true documents Deprecation and Sunset on every 2xx response (header names are case-insensitive) |
See also#
- Versioning: when a new major version is needed.
- Create a version and deprecate one: what subscribers see today.
Updated 2026-10-17