]> Wiremind

srmili@wiremind.io

Web and Internet Transport HTTPAPI HTTP deprecation sunset lifecycle JSON The Deprecation and Sunset HTTP response header fields, defined in RFC 9745 and RFC 8594 respectively, let a server signal that a resource, identified by its URI, has been or will be deprecated and when it will be removed. They operate at the granularity of a resource and cannot describe the lifecycle of an individual member within a request or response representation. This document defines the "application/deprecations+json" media type, a machine-readable Deprecation Manifest in which an API operator declares dated deprecation and sunset timelines for specific members of request and response representations. The manifest is discovered through the existing "deprecation" link relation type and is decoupled from any API description or schema, allowing each deployment to publish its own timeline without changing the wire behaviour of the API. About This Document Status information for this document may be found at . Discussion of this document takes place on the HTTPAPI Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction HTTP APIs evolve. A common evolution is to introduce a new representation member that replaces an older one, while continuing to accept or return the older member for a transition period. The operator of such an API needs to communicate, to the consumers of the API, that the older member is on its way out and the date after which it will no longer be supported. The Deprecation HTTP response header field and the Sunset HTTP response header field address this need at the granularity of a resource: they describe the resource identified by the request URI. They do not, and by design cannot, name an individual member inside a JSON request or response body. HTTP header fields describe the message or the resource, not the substructure of a representation. At the same time, the mechanisms that can name an individual member, namely the deprecated keyword of the OpenAPI Specification and of JSON Schema , are design-time annotations baked into a single shared description. They carry no date, and they describe the contract rather than a particular deployment of it. An operator who supports a shared, multi-party API specification cannot use them to express "on my deployment, this member will stop being accepted on this date". No existing mechanism combines all three properties that this situation requires:

1. member-level granularity (which field, not just which resource);
2. dated lifecycle (a deprecation date and a sunset date); and
3. per-deployment, runtime discoverability (decoupled from the schema).

This document fills that gap with a Deprecation Manifest: a JSON document, served with the "application/deprecations+json" media type, in which an operator declares dated deprecation and sunset information for individual members of request and response representations. The manifest reuses the date semantics of and and is discovered through the "deprecation" link relation type registered by . The manifest is purely informational. It does not alter the behaviour of any resource, and conformance to it imposes no requirement on a server to accept or reject any particular member (see ).

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses the term "member" as defined by : a name/value pair within a JSON object. The terms "consumer" and "operator" refer, respectively, to a client of an HTTP API and to the party that operates the server.

The Deprecation Manifest A Deprecation Manifest is a JSON document whose media type is "application/deprecations+json" (). Its root is a JSON object with the following members:

Member	Type	Required	Description
deprecations	array	yes	An array of Deprecation Entry objects ().

A consumer MUST ignore any member it does not recognise. An operator MAY include additional members; this document does not define their meaning.

An example Deprecation Manifest

The Deprecation Entry Object Each element of the deprecations array is a Deprecation Entry: a JSON object describing the lifecycle of a single member, identified by a selector (), within the representations of a single target ().

Member	Type	Required	Description
target	string	yes	Identifies the operation or resource the entry applies to ().
direction	string	yes	"request" or "response" ().
selector	string	yes	Locates the deprecated member ().
selectorType	string	no	"jsonpath" (default) or "jsonpointer" ().
replacedBy	string	no	A selector, of the same selectorType, for the replacement member.
deprecation	string	no	The date the member is or was deprecated ().
sunset	string	no	The date after which the member will no longer be supported ().
info	string	no	A URI of human-readable documentation about the deprecation.
description	string	no	A short human-readable explanation.

The target Member The target member identifies the operation or resource to which the entry applies. Its value is a string. When the operation is best identified by an HTTP method and a path, the value SHOULD be the method (in uppercase) followed by a single space and a path or path template, for example "POST /offers" or "GET /offers/{offerId}". An operator MAY use any other stable identifier its consumers can resolve; the meaning of such identifiers is out of scope for this document.

The direction Member The direction member indicates whether the selector applies to the representation a consumer sends in a request ("request") or to the representation a server returns in a response ("response"). A consumer MUST treat an entry whose direction it does not recognise as having no defined meaning and SHOULD ignore it.

The selector and selectorType Members The selector member locates the deprecated member within the relevant representation. The interpretation of selector is governed by selectorType:

• "jsonpath" (the default when selectorType is absent): selector is a JSONPath expression as defined in .
• "jsonpointer": selector is a JSON Pointer as defined in .

A consumer that does not implement the indicated selectorType MUST ignore the entry. The replacedBy member, when present, uses the same selectorType as the entry's selector. This document defines selectors only for representations whose media type is JSON or a media type using the structured "+json" suffix. Selectors for other media types are out of scope ().

The deprecation and sunset Members The deprecation member carries the date on which the member is, or was, deprecated; it MAY be in the past or the future. The sunset member carries the date after which the operator intends to stop supporting the member. These members reuse, at member granularity, the semantics of the Deprecation and Sunset header fields respectively. The value of each is a string containing a date, or a date and time, formatted as a full-date or date-time as defined in . A consumer MUST NOT assume that the absence of a sunset member implies any particular removal date.

Discovery A server makes a Deprecation Manifest discoverable by means of the "deprecation" link relation type registered by . Where uses that relation to point to human-readable documentation, this document allows the same relation to point to a machine-readable manifest, distinguished by its media type. A server MAY include, in HTTP responses or in a resource representation, a link () with relation type "deprecation" and a type target attribute of "application/deprecations+json" whose target URI is a Deprecation Manifest: ; rel="deprecation"; type="application/deprecations+json" ]]> A consumer that retrieves the linked manifest can determine, for the members it sends or receives, whether any is deprecated and when it is scheduled to be sunset, without parsing per-response signals. A server MAY also make a manifest available at a stable, operator-chosen URI advertised out of band. The definition of a well-known URI for this purpose is left to future work. Publishing API metadata as a document that is discovered through a link relation or a well-known URI is an established pattern; the api-catalog well-known URI is one example.

Relationship to the Deprecation and Sunset Header Fields For deprecation at the granularity of a resource, the Deprecation and Sunset header fields remain the mechanism of choice. They are conveyed in band, on a response the consumer is already retrieving, and require no additional request. This document does not change or supersede them. The Deprecation Manifest addresses the case those header fields cannot express: the deprecation of an individual member within a representation. An entry MAY omit its selector to describe a whole resource, but this is a convenience that lets an operator list resource-level and member-level deprecations in one place; it is not intended to replace the header fields. Where a resource is described both by a header field and by a manifest entry, the two are expected to convey consistent dates.

Resource Behaviour Consistent with , the presence of an entry in a Deprecation Manifest does not change the behaviour of any resource. A member that is listed as deprecated, and even one whose sunset date has passed, may still be accepted or returned by the server. The manifest expresses the operator's intent; it is advisory metadata and imposes no protocol-level requirement on either party. Consumers are advised to migrate away from a deprecated member before its sunset date.

Limitations The scope of this document is constrained as follows:

• It defines a proactive, out-of-band declaration. It does not define an in-band signal that names, within a specific response, a deprecated member that the consumer used in the corresponding request. The Deprecation and Sunset header fields describe the resource, not a body member, and Problem Details is defined for error conditions, whereas an accepted-but-deprecated member is not an error. In-band member-level signalling is left to future work or to ecosystem-specific conventions.
• It defines selectors for JSON representations only.
• It does not provide a means to authenticate the manifest beyond the transport-level protections discussed in .

Security Considerations A Deprecation Manifest is a hint and SHOULD be treated as such; see the corresponding considerations in . A manifest, or a "deprecation" link advertising one, that is obtained over an unsecured channel may be forged or altered by an intermediary, for example to suppress a sunset date or to point a consumer at misleading documentation. Consumers SHOULD obtain manifests over an authenticated, integrity-protected channel and SHOULD verify that the info and manifest URIs belong to the expected operator. Because acting on a future-dated sunset automatically (for example by disabling a code path) can cause a consumer to stop sending a member earlier than necessary, consumers SHOULD surface such dates to their developers rather than enforce them without review.

IANA Considerations

The "application/deprecations+json" Media Type IANA is requested to register the following media type in the "Media Types" registry, per .

Type name:

application

Subtype name:

deprecations+json

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

binary; the content is a JSON document encoded in UTF-8.

Security considerations:

See of RFC XXXX.

Interoperability considerations:

See RFC XXXX.

Published specification:

RFC XXXX

Applications that use this media type:

HTTP API clients and servers that exchange member-level deprecation information.

Fragment identifier considerations:

As specified for the "+json" suffix in .

Additional information:

Deprecated alias names for this type:

N/A

Magic number(s):

N/A

File extension(s):

N/A

Macintosh file type code(s):

N/A

Person and email address to contact for further information:

Sami Rmili (srmili@wiremind.io)

Intended usage:

COMMON

Restrictions on usage:

N/A

Author:

Sami Rmili

Change controller:

IETF

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). It also defines the serialisation of such links in HTTP headers with the Link header field. The Deprecation HTTP response header field is used to signal to consumers of a resource (identified by a URI) that the resource will be or has been deprecated. Additionally, the deprecation link relation can be used to link to a resource that provides further information about planned or existing deprecation. It may also provide ways in which client application developers can best manage deprecation. JSONPath defines a string syntax for selecting and extracting JSON (RFC 8259) values from within a given JSON value. JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. A content media type name sometimes includes partitioned meta- information distinguished by a structured syntax to permit noting an attribute of the media as a suffix to the name. This document defines several structured syntax suffixes for use with media type registrations. In particular, it defines and registers the "+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip" structured syntax suffixes, and provides a media type structured syntax suffix registration form for the "+xml" structured syntax suffix. This document is not an Internet Standards Track specification; it is published for informational purposes. Informative References This specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future. It also defines a sunset link relation type that allows linking to resources providing information about an upcoming resource or service sunset. This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. This document defines the "api-catalog" well-known URI and link relation. It is intended to facilitate automated discovery and usage of published Application Programming Interfaces (APIs). A request to the api-catalog resource will return a document providing information about, and links to, the Publisher's APIs. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry.

Acknowledgements This work was inspired by the Deprecation and Sunset HTTP header fields and by the practical needs of operators of multi-party HTTP API specifications.