Skip to content

Latest commit

 

History

History
130 lines (99 loc) · 5.28 KB

deprecation.adoc

File metadata and controls

130 lines (99 loc) · 5.28 KB
Raw

REST Design - Deprecation

Sometimes it is necessary to phase out an API endpoint, an API version, or an API feature, e.g. if a field or parameter is no longer supported or a whole business functionality behind an endpoint is supposed to be shut down. As long as the API endpoints and features are still used by consumers these shut downs are breaking changes and not allowed. To progress the following deprecation rules have to be applied to make sure that the necessary consumer changes and actions are well communicated and aligned using deprecation and sunset dates.

{MUST} reflect deprecation in API specifications

The API deprecation must be part of the API specification.

If an API endpoint (operation object), an input argument (parameter object), an in/out data object (schema object), or on a more fine grained level, a schema attribute or property should be deprecated, the producers must set deprecated: true for the affected element and add further explanation to the description section of the API specification. If a future shut down is planned, the producer must provide a sunset date and document in details what consumers should use instead and how to migrate.

{MUST} obtain approval of clients before API shut down

Before shutting down an API, version of an API, or API feature the producer must make sure, that all clients have given their consent on a sunset date. Producers should help consumers to migrate to a potential new API or API feature by providing a migration manual and clearly state the time line for replacement availability and sunset (see also {SHOULD} add Deprecation and Sunset header to responses). Once all clients of a sunset API feature are migrated, the producer may shut down the deprecated API feature.

{MUST} collect external partner consent on deprecation time span

If the API is consumed by any external partner, the API owner must define a reasonable time span that the API will be maintained after the producer has announced deprecation. All external partners must state consent with this after-deprecation-life-span, i.e. the minimum time span between official deprecation and first possible sunset, before they are allowed to use the API.

{MUST} monitor usage of deprecated API scheduled for sunset

Owners of an API, API version, or API feature used in production that is scheduled for sunset must monitor the usage of the sunset API, API version, or API feature in order to observe migration progress and avoid uncontrolled breaking effects on ongoing consumers. See also [193].

{SHOULD} add Deprecation and Sunset header to responses

During the deprecation phase, the producer should add a Deprecation: <date-time> (see draft: RFC Deprecation HTTP Header Field) and - if also planned - a Sunset: <date-time> (see {RFC-8594}#section-3[RFC 8594]) header on each response affected by a deprecated element (see {MUST} reflect deprecation in API specifications).

The {Deprecation} header can either be set to true - if a feature is retired -, or carry a deprecation time stamp, at which a replacement will become/became available and consumers must not on-board any longer (see {MUST} not start using deprecated APIs). The optional {Sunset} time stamp carries the information when consumers latest have to stop using a feature. The sunset date should always offer an eligible time interval for switching to a replacement feature.

Deprecation: Tue, 31 Dec 2024 23:59:59 GMT
Sunset: Wed, 31 Dec 2025 23:59:59 GMT

If multiple elements are deprecated the {Deprecation} and {Sunset} headers are expected to be set to the earliest time stamp to reflect the shortest interval at which consumers are expected to get active. The {Deprecation} and {Sunset} headers can be defined as follows in the API specification (see also the default definition below):

components:
  parameters|headers:
    Deprecation:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/Deprecation'
    Sunset:
      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/Sunset'
link:../includes/deprecation.yaml[role=include]
link:../includes/sunset.yaml[role=include]

Note: adding the {Deprecation} and {Sunset} header is not sufficient to gain client consent to shut down an API or feature.

Hint: In earlier guideline versions, we used the {Warning} header to provide the deprecation info to clients. However, {Warning} header has a less specific semantics, will be obsolete with draft: RFC HTTP Caching, and our syntax was not compliant with {RFC-9111}#section-5.5[RFC 9111 Section 5.5 "Warning"].

{SHOULD} add monitoring for Deprecation and Sunset header

Clients should monitor the {Deprecation} and {Sunset} headers in HTTP responses to get information about future sunset of APIs and API features (see {SHOULD} add Deprecation and Sunset header to responses). We recommend that client owners build alerts on this monitoring information to ensure alignment with service owners on required migration task.

Hint: In earlier guideline versions, we used the Warning header to provide the deprecation info (see hint in {SHOULD} add Deprecation and Sunset header to responses).

{MUST} not start using deprecated APIs

Clients must not start using deprecated APIs, API versions, or API features.