draft-dalal-deprecation-header-03.xml

<?xml version="1.0" encoding="utf-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.2.9 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc docName="draft-dalal-deprecation-header-03" category="std">

  <front>
    <title>The Deprecation HTTP Header Field</title>

    <author initials="S." surname="Dalal" fullname="Sanjay Dalal">
      <organization></organization>
      <address>
        <email>sanjay.dalal@cal.berkeley.edu</email>
        <uri>https://github.com/sdatspun2</uri>
      </address>
    </author>
    <author initials="E." surname="Wilde" fullname="Erik Wilde">
      <organization></organization>
      <address>
        <email>erik.wilde@dret.net</email>
        <uri>http://dret.net/netdret</uri>
      </address>
    </author>

    <date year="2020" month="June" day="13"/>

    
    
    

    <abstract>


<t>The HTTP Deprecation response header field can be used to signal to consumers of a URI-identified resource that the resource has been deprecated. Additionally, the deprecation link relation can be used to link to a resource that provides additional context for the deprecation, and possibly ways in which clients can find a replacement for the deprecated resource.</t>



    </abstract>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>Deprecation of an HTTP resource as defined in Section 2 of <xref target="RFC7231"/> is a technique to communicate information about the lifecycle of a resource. It encourages applications to migrate away from the resource, discourages applications from forming new dependencies on the resource, and informs applications about the risk of continuing dependence upon the resource.</t>

<t>The act of deprecation does not change any behavior of the resource. It just informs client of the fact that a resource is deprecated. The Deprecation HTTP response header field MAY be used to convey this fact at runtime to clients. The header field can carry information indicating since when the deprecation is in effect.</t>

<t>In addition to the Deprecation header field the resource provider can use other header fields to convey additional information related to deprecation. For example, information such as where to find documentation related to the deprecation or what should be used as an alternate and when the deprecated resource would be unreachable, etc. Alternates of a resource can be similar resource(s) or a newer version of the same resource.</t>

<section anchor="notational-conventions" title="Notational Conventions">

<t>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 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals, as shown here.</t>

<t>This specification uses the Augmented Backus-Naur Form (ABNF) notation of <xref target="RFC5234"/> and includes, by reference, the IMF-fixdate rule as defined in Section 7.1.1.1 of <xref target="RFC7231"/>.</t>

<t>The term “resource” is to be interpreted as defined in Section 2 of <xref target="RFC7231"/>, that is identified by an URI.</t>

</section>
</section>
<section anchor="the-deprecation-http-response-header-field" title="The Deprecation HTTP Response Header Field">

<t>The <spanx style="verb">Deprecation</spanx> HTTP response header field allows a server to communicate to a client that the resource in context of the message is or will be deprecated.</t>

<section anchor="syntax" title="Syntax">

<t>The <spanx style="verb">Deprecation</spanx> response header field describes the deprecation. It either shows the deprecation date, which may be in the future (the resource context will be deprecated at that date) or in the past (the resource context has been deprecated at that date), or it simply flags the resource context as being deprecated:</t>

<figure><artwork><![CDATA[
Deprecation = IMF-fixdate / "true"
]]></artwork></figure>

<t>Servers MUST NOT include more than one <spanx style="verb">Deprecation</spanx> header field in the same response.</t>

<t>The date, if present, is the date when the resource context was or will be deprecated. It is in the form of an IMF-fixdate timestamp.</t>

<t>The following example shows that the resource context has been deprecated on Friday, November 11, 2018 at 23:59:59 GMT:</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
]]></artwork></figure>

<t>The deprecation date can be in the future. If the value of <spanx style="verb">date</spanx> is in the future, it means that the resource will be deprecated at the given date in future.</t>

<t>If the deprecation date is not known, the header field can carry the simple string “true”, indicating that the resource context is deprecated, without indicating when that happened:</t>

<figure><artwork><![CDATA[
    Deprecation: true
]]></artwork></figure>

</section>
</section>
<section anchor="the-deprecation-link-relation-type" title="The Deprecation Link Relation Type">

<t>In addition to the Deprecation HTTP header field, the server can use links with the “deprecation” link relation type to communicate to the client where to find more information about deprecation of the context. This can happen before the actual deprecation, to make a deprecation policy discoverable, or after deprecation, when there may be documentation about the deprecation, and possibly documentation of how to manage it.</t>

<t>This specification places no restrictions on the representation of the interlinked deprecation policy. In particular, the deprecation policy may be available as human-readable documentation or as machine-readable description.</t>

<section anchor="documentation" title="Documentation">

<t>For a resource, deprecation could involve one or more parts of request, response or both. These parts could be one or more of the following.</t>

<t><list style="symbols">
  <t>URI - deprecation of one ore more query parameter(s) or path element(s)</t>
  <t>method - HTTP method for the resource is deprecated</t>
  <t>request header - one or more HTTP request header(s) is deprecated</t>
  <t>response header - HTTP response header(s) is deprecated</t>
  <t>request body - request body contains one or more deprecated element(s)</t>
  <t>response body - response body contains one or more deprecated element(s)</t>
</list></t>

<t>The purpose of the <spanx style="verb">Deprecation</spanx> header is to provide just enough “hints” about the deprecation to the client application developer. It is safe to assume that on reception of the <spanx style="verb">Deprecation</spanx> header, the client developer would look up the resource’s documentation in order to find deprecation related semantics. The resource developer could provide a link to the resource documentation using a <spanx style="verb">Link</spanx> header with relation type <spanx style="verb">deprecation</spanx> as shown below.</t>

<figure><artwork><![CDATA[
Link: <https://developer.example.com/deprecation>; 
      rel="deprecation"; type="text/html"
]]></artwork></figure>

<t>In this example the interlinked content provides additional information about the deprecation of the resource context. There is no Deprecation header field in the response, and thus the resource is not deprecated. However, the resource already exposes a link where information is available how deprecation is managed for the context. This may be documentation explaining the use of the Deprecation header field, and also explaining under which circumstances and with which policies (announcement before deprecation; continued operation after deprecation) deprecation might be happening.</t>

<t>The following example uses the same link header, but also announces a deprecation date using a Deprecation header field.</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://developer.example.com/deprecation>; 
      rel="deprecation"; type="text/html"
]]></artwork></figure>

<t>Given that the deprecation date is in the past, the linked resource may have been updated to include information about the deprecation, allowing clients to discover information about the deprecation that happened.</t>

</section>
</section>
<section anchor="recommend-replacement" title="Recommend Replacement">

<t><spanx style="verb">Link</spanx> <xref target="RFC8288"/> header could be used in addition to the <spanx style="verb">Deprecation</spanx> header to recommend the client application about available alternates to the deprecated resource. Following relation types as defined in <xref target="RFC8288"/> are RECOMMENDED to use for the purpose.</t>

<t><list style="symbols">
  <t><spanx style="verb">successor-version</spanx>: Points to a resource containing the successor version. <xref target="RFC5829"/></t>
  <t><spanx style="verb">latest-version</spanx>: Points to a resource containing the latest (e.g., current) version. <xref target="RFC5829"/></t>
  <t><spanx style="verb">alternate</spanx>: Designates a substitute. [W3C.REC-html401-19991224]</t>
</list></t>

<t>The following example provides link to the successor version of the requested resource that is deprecated.</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version"
]]></artwork></figure>

<t>This example provides link to an alternate resource to the requested resource that is deprecated.</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v1/clients>; rel="alternate"
]]></artwork></figure>

</section>
<section anchor="sunset" title="Sunset">

<t>In addition to the deprecation related information, if the resource provider wants to convey to the client application that the deprecated resource is expected to become unresponsive at a specific point in time, the Sunset HTTP header field <xref target="RFC8594"/> can be used in addition to the <spanx style="verb">Deprecation</spanx> header.</t>

<t>The timestamp given in the <spanx style="verb">Sunset</spanx> header field MUST be the later or the same as the one given in the <spanx style="verb">Deprecation</spanx> header field.</t>

<t>The following example shows that the resource in context has been deprecated since Sunday, November 11, 2018 at 23:59:59 GMT and its sunset date is Wednesday, November 11, 2020 at 23:59:59 GMT.</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Wed, 11 Nov 2020 23:59:59 GMT
]]></artwork></figure>

</section>
<section anchor="resource-behavior" title="Resource Behavior">

<t>The act of deprecation does not change any behavior of the resource. Deprecated resources SHOULD keep functioning as before, allowing consumers to still use the resources in the same way as they did before the resources were declared deprecated.</t>

</section>
<section anchor="iana-considerations" title="IANA Considerations">

<section anchor="the-deprecation-http-response-header-field-1" title="The Deprecation HTTP Response Header Field">

<t>The <spanx style="verb">Deprecation</spanx> response header should be added to the permanent registry of message header fields (see <xref target="RFC3864"/>), taking into account the guidelines given by HTTP/1.1 <xref target="RFC7231"/>.</t>

<figure><artwork><![CDATA[
Header Field Name: Deprecation

Applicable Protocol: Hypertext Transfer Protocol (HTTP)

Status: Standard

Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>, 
        Erik Wilde <erik.wilde@dret.net>

Change controller: IETF

Specification document: this specification, 
            Section 2 "The Deprecation HTTP Response Header Field"
]]></artwork></figure>

</section>
<section anchor="the-deprecation-link-relation-type-1" title="The Deprecation Link Relation Type">

<t>The <spanx style="verb">deprecation</spanx> link relation type should be added to the permanent registry of link relation types according to Section 4.2 of <xref target="RFC8288"/>:</t>

<figure><artwork><![CDATA[
Relation Type: deprecation

Applicable Protocol: Hypertext Transfer Protocol (HTTP)

Status: Standard

Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>, 
        Erik Wilde <erik.wilde@dret.net>

Change controller: IETF

Specification document: this specification, 
        Section 3 "The Deprecation Link Relation Type"
]]></artwork></figure>

</section>
</section>
<section anchor="implementation-status" title="Implementation Status">

<t>Note to RFC Editor: Please remove this section before publication.</t>

<t>This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in <xref target="RFC7942"/>.  The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs.  Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors.  This is not intended as, and must not be construed to be, a catalog of available implementations or their features.  Readers are advised to note that
other implementations may exist.</t>

<t>According to RFC 7942, “this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit”.</t>

<section anchor="implementing-the-deprecation-header-field" title="Implementing the Deprecation Header Field">

<t>This is a list of implementations that implement the deprecation header field:</t>

<t>Organization: Apollo</t>

<t><list style="symbols">
  <t>Description: Deprecation header is returned when deprecated functionality (as declared in the GraphQL schema) is accessed</t>
  <t>Reference: https://www.npmjs.com/package/apollo-server-tools</t>
</list></t>

<t>Organization: Zalando</t>

<t><list style="symbols">
  <t>Description: Deprecation header is recommended as the preferred way to communicate API deprecation in Zalando API designs.</t>
  <t>Reference: https://opensource.zalando.com/restful-api-guidelines/#deprecation</t>
</list></t>

<t>Organization: Palantir Technologies</t>

<t><list style="symbols">
  <t>Description: Deprecation header is incorporated in code generated by conjure-java, a CLI to generate Java POJOs and interfaces from Conjure API definitions</t>
  <t>Reference: https://github.com/palantir/conjure-java</t>
</list></t>

<t>Organization: IETF Internet Draft, Registration Protocols Extensions</t>

<t><list style="symbols">
  <t>Description: Deprecation link relation is returned in Registration Data Access Protocol (RDAP) notices to indicate deprecation of jCard in favor of JSContact.</t>
  <t>Reference: https://tools.ietf.org/html/draft-loffredo-regext-rdap-jcard-deprecation</t>
</list></t>

<t>Organization:  E-Voyageurs Technologies</t>

<t><list style="symbols">
  <t>Description: Deprecation header is incorporated in Hesperides, a configuration management tool providing universal text file templating and properties editing through a REST API or a webapp.</t>
  <t>Reference: https://github.com/voyages-sncf-technologies/hesperides/blob/master/documentation/lightweight-architecture-decision-records/deprecated_endpoints.md</t>
</list></t>

<t>Organization: Open-Xchange</t>

<t><list style="symbols">
  <t>Description: Deprecation header is used in Open-Xchange appsuite-middleware</t>
  <t>Reference: https://github.com/open-xchange/appsuite-middleware</t>
</list></t>

<t>Organization: MediaWiki</t>

<t><list style="symbols">
  <t>Description: Core REST API of MediaWiki would use Deprecation header for endpoints that have been deprecated because a new endpoint provides the same or better functionality.</t>
  <t>Reference: https://phabricator.wikimedia.org/T232485</t>
</list></t>

</section>
<section anchor="implementing-the-concept" title="Implementing the Concept">

<t>This is a list of implementations that implement the general concept, but do so using different mechanisms:</t>

<t>Organization: Zapier</t>

<t><list style="symbols">
  <t>Description: Zapier uses two custom HTTP headers named <spanx style="verb">X-API-Deprecation-Date</spanx> and <spanx style="verb">X-API-Deprecation-Info</spanx></t>
  <t>Reference:  https://zapier.com/engineering/api-geriatrics/</t>
</list></t>

<t>Organization: IBM</t>

<t><list style="symbols">
  <t>Description: IBM uses a custom HTTP header named <spanx style="verb">Deprecated</spanx></t>
  <t>Reference: https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/com.ibm.qradar.doc/c_rest_api_getting_started.html</t>
</list></t>

<t>Organization: Ultipro</t>

<t><list style="symbols">
  <t>Description: Ultipro uses the HTTP <spanx style="verb">Warning</spanx> header as described in Section 5.5 of <xref target="RFC7234"/> with code <spanx style="verb">299</spanx></t>
  <t>Reference:  https://connect.ultipro.com/api-deprecation</t>
</list></t>

<t>Organization: Clearbit</t>

<t><list style="symbols">
  <t>Description: Clearbit uses a custom HTTP header named <spanx style="verb">X-API-Warn</spanx></t>
  <t>Reference: https://blog.clearbit.com/dealing-with-deprecation/</t>
</list></t>

<t>Organization: PayPal</t>

<t><list style="symbols">
  <t>Description: PayPal uses a custom HTTP header named <spanx style="verb">PayPal-Deprecated</spanx></t>
  <t>Reference: https://github.com/paypal/api-standards/blob/master/api-style-guide.md#runtime</t>
</list></t>

</section>
</section>
<section anchor="security-considerations" title="Security Considerations">

<t>The Deprecation header field SHOULD be treated as a hint, meaning that the resource is indicating (and not guaranteeing with certainty) that it is deprecated. Applications consuming the resource SHOULD check the resource documentation to verify authenticity and accuracy. Resource documentation SHOULD provide additional information about the deprecation including recommendation(s) for replacement.</t>

<t>In cases, where the Deprecation header field value is a date in future, it can lead to information that otherwise might not be available. Therefore, applications consuming the resource SHOULD verify the resource documentation and if possible, consult the resource developer to discuss potential impact due to deprecation and plan for possible transition to recommended resource.</t>

<t>In cases where <spanx style="verb">Link</spanx> header is used to provide more documentation and/or recommendation for replacement, one should assume that the content of the  <spanx style="verb">Link</spanx> header field may not be secure, private or integrity-guaranteed, and due caution should be exercised when using it. Applications consuming the resource SHOULD check the referred resource documentation to verify authenticity and accuracy.</t>

<t>The suggested <spanx style="verb">Link</spanx> header fields make extensive use of IRIs and URIs. See <xref target="RFC3987"/> for security considerations relating to IRIs. See <xref target="RFC3986"/> for security considerations relating to URIs. See <xref target="RFC7230"/> for security considerations relating to HTTP headers.</t>

<t>Applications that take advantage of typed links should consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from the HTTP headers. In particular, Link headers that use the <spanx style="verb">successor-version</spanx>, <spanx style="verb">latest-version</spanx> or <spanx style="verb">alternate</spanx> relation types should be treated with due caution. See <xref target="RFC5829"/> for security considerations relating to these link relation types.</t>

</section>
<section anchor="examples" title="Examples">

<t>The first example shows a deprecation header field without date information:</t>

<figure><artwork><![CDATA[
Deprecation: true
]]></artwork></figure>

<t>The second example shows a deprecation header with date information and a link to the successor version:</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version"
]]></artwork></figure>

<t>The third example shows a deprecation header field with links for the successor version and for the API’s deprecation policy. In addition, it shows the sunset date for the deprecated resource:</t>

<figure><artwork><![CDATA[
Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Wed, 11 Nov 2020 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version", 
      <https://developer.example.com/deprecation>; rel="deprecation"
]]></artwork></figure>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor="RFC7231" target='https://www.rfc-editor.org/info/rfc7231'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.</t></abstract>
</front>
<seriesInfo name='RFC' value='7231'/>
<seriesInfo name='DOI' value='10.17487/RFC7231'/>
</reference>



<reference  anchor="RFC2119" target='https://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>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.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor="RFC8174" target='https://www.rfc-editor.org/info/rfc8174'>
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author initials='B.' surname='Leiba' fullname='B. Leiba'><organization /></author>
<date year='2017' month='May' />
<abstract><t>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.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='8174'/>
<seriesInfo name='DOI' value='10.17487/RFC8174'/>
</reference>



<reference  anchor="RFC5234" target='https://www.rfc-editor.org/info/rfc5234'>
<front>
<title>Augmented BNF for Syntax Specifications: ABNF</title>
<author initials='D.' surname='Crocker' fullname='D. Crocker' role='editor'><organization /></author>
<author initials='P.' surname='Overell' fullname='P. Overell'><organization /></author>
<date year='2008' month='January' />
<abstract><t>Internet technical specifications often need to define a formal syntax.  Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications.  The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power.  The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges.  This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='68'/>
<seriesInfo name='RFC' value='5234'/>
<seriesInfo name='DOI' value='10.17487/RFC5234'/>
</reference>



<reference  anchor="RFC8288" target='https://www.rfc-editor.org/info/rfc8288'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<date year='2017' month='October' />
<abstract><t>This specification defines a model for the relationships between resources on the Web (&quot;links&quot;) and the type of those relationships (&quot;link relation types&quot;).</t><t>It also defines the serialisation of such links in HTTP headers with the Link header field.</t></abstract>
</front>
<seriesInfo name='RFC' value='8288'/>
<seriesInfo name='DOI' value='10.17487/RFC8288'/>
</reference>



<reference  anchor="RFC3864" target='https://www.rfc-editor.org/info/rfc3864'>
<front>
<title>Registration Procedures for Message Header Fields</title>
<author initials='G.' surname='Klyne' fullname='G. Klyne'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='J.' surname='Mogul' fullname='J. Mogul'><organization /></author>
<date year='2004' month='September' />
<abstract><t>This specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='90'/>
<seriesInfo name='RFC' value='3864'/>
<seriesInfo name='DOI' value='10.17487/RFC3864'/>
</reference>



<reference  anchor="RFC7234" target='https://www.rfc-editor.org/info/rfc7234'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t></abstract>
</front>
<seriesInfo name='RFC' value='7234'/>
<seriesInfo name='DOI' value='10.17487/RFC7234'/>
</reference>



<reference  anchor="RFC3987" target='https://www.rfc-editor.org/info/rfc3987'>
<front>
<title>Internationalized Resource Identifiers (IRIs)</title>
<author initials='M.' surname='Duerst' fullname='M. Duerst'><organization /></author>
<author initials='M.' surname='Suignard' fullname='M. Suignard'><organization /></author>
<date year='2005' month='January' />
<abstract><t>This document defines a new protocol element, the Internationalized  Resource Identifier (IRI), as a complement of the Uniform Resource  Identifier (URI). An IRI is a sequence of characters from the  Universal Character Set (Unicode/ISO 10646). A mapping from IRIs to   URIs is defined, which means that IRIs can be used instead of URIs,  where appropriate, to identify resources.</t><t> The approach of defining a new protocol element was chosen instead of extending or changing the definition of URIs.  This was done in order  to allow a clear distinction and to avoid incompatibilities with  existing software. Guidelines are provided for the use and deployment of IRIs in various protocols, formats, and software components that currently deal with URIs.</t></abstract>
</front>
<seriesInfo name='RFC' value='3987'/>
<seriesInfo name='DOI' value='10.17487/RFC3987'/>
</reference>



<reference  anchor="RFC3986" target='https://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>



<reference  anchor="RFC7230" target='https://www.rfc-editor.org/info/rfc7230'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the &quot;http&quot; and &quot;https&quot; Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract>
</front>
<seriesInfo name='RFC' value='7230'/>
<seriesInfo name='DOI' value='10.17487/RFC7230'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor="RFC5829" target='https://www.rfc-editor.org/info/rfc5829'>
<front>
<title>Link Relation Types for Simple Version Navigation between Web Resources</title>
<author initials='A.' surname='Brown' fullname='A. Brown'><organization /></author>
<author initials='G.' surname='Clemm' fullname='G. Clemm'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2010' month='April' />
<abstract><t>This specification defines a set of link relation types that may be used on Web resources for navigation between a resource and other resources related to version control, such as past versions and working copies.  This document is not an Internet Standards Track  specification; it is published for informational purposes.</t></abstract>
</front>
<seriesInfo name='RFC' value='5829'/>
<seriesInfo name='DOI' value='10.17487/RFC5829'/>
</reference>



<reference  anchor="RFC8594" target='https://www.rfc-editor.org/info/rfc8594'>
<front>
<title>The Sunset HTTP Header Field</title>
<author initials='E.' surname='Wilde' fullname='E. Wilde'><organization /></author>
<date year='2019' month='May' />
<abstract><t>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.</t></abstract>
</front>
<seriesInfo name='RFC' value='8594'/>
<seriesInfo name='DOI' value='10.17487/RFC8594'/>
</reference>



<reference  anchor="RFC7942" target='https://www.rfc-editor.org/info/rfc7942'>
<front>
<title>Improving Awareness of Running Code: The Implementation Status Section</title>
<author initials='Y.' surname='Sheffer' fullname='Y. Sheffer'><organization /></author>
<author initials='A.' surname='Farrel' fullname='A. Farrel'><organization /></author>
<date year='2016' month='July' />
<abstract><t>This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section.  This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature.</t><t>This process is not mandatory.  Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications.  This document obsoletes RFC 6982, advancing it to a Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='205'/>
<seriesInfo name='RFC' value='7942'/>
<seriesInfo name='DOI' value='10.17487/RFC7942'/>
</reference>




    </references>


<section anchor="acknowledgments" title="Acknowledgments">

<t>The authors would like to thank Nikhil Kolekar, Mark Nottingham, and Roberto Polli for their contributions.</t>

<t>The authors take all responsibility for errors and omissions.</t>

</section>


  </back>

<!-- ##markdown-source:
H4sIAGPf5F4AA+1bbXfbxpX+zl8xK3+o3UOQkWzXtpJ0q0h2rKxfVEluuu3p
sYbAkBwLBNgZQDLT4/++z70zAwxA0JbT7H7a0yahSMzMnfv63BckSTJKy0wX
i0NRV/Pk6WhU6SpXh+JyqcSJWhuVykqXhXh5eXkmXiqZKSNeaJVno6xMC7nC
o5mR8yrJZC7zJGuXJEt+Ovnm4QhfqEVpNofCVtloZCtZZO9lXhZYvVF2tNaH
4u9VmY4F/qWLTBXVWNjSVEbNLT5tVv5DZXSKn9JytZb+wwoP4ydd5LpQ/xiN
ZF0tS3M4EiLBPwI/2ENxMREnRB9/46i+kMUHuYm+Viupc1DI30/4On9KZT6Z
KXOtcrWZqKzmB2sDcpdVtbaH0+lCV8t6NgEhU5vJyq7r4oDOpgfb859PxM86
z1R0/nOjr6Mv/ekK305u6ds/ZUZVk0JV3TNxZPhhin/o82hUlGYFnt+ow9FI
F/P2L6YiSRIhZ+AdWDYakWBZmLF0jbLrsrBKOJmJOUlYpLIQMyVqqzIIRli9
KGROn1I8W6+UsaKcCynenZ8mmoSmsS6jzcrapEpUS1nhX6r9ZiktdlSFCHqi
sok4yjJNVMg834z5+UiLBMR6jQ1y91ePJP4R/5W9Q9emvAFFVshmbyK6Uh8r
Afb0DxkLKKRYl9bqWb4Rt3JjITdxu9TpUqS5JhXjo+dQTj5snctUkeptbRcx
YDIaMfNXOstyhT9G98RpUZkyq1M6djSKZUCs9HbWXAbsyhQOxaag50LxMnFA
z/7rX/9x/uL4ycHD/U+fhMZNRaXSZaH/WSsnotWqLjQRJBqVwFo5K2snlFzP
VbpJc+WE2BAtTiuhihR/yAVxcL3OtSPR0sYrvTC0qQSXxNyUq46ExyLTdngt
P0uEwNuIQt0SxxTZeqrxKEjr7kMScYT39mlvYLS9JuJJsrqoad9mT+jIurfn
RDjthxnQqljJshIkFGUl0qUsFnik2EDNlvJGQ7p4trsNGPShtlVDntOQ8Nyc
9mctjLRS247KD3rXYSN8ffTfscbjrjdqg/2xI5+Ec0yN+6+c2J2yuhO2jDmV
xmw66gB9ZsaCdVYT126XqtiyQc3moOZQmIq4eFo0hkWHVr3bdM7t2L+3S8PU
4EqixM+ms8BGt4ysNyaavYFjR0TlRLyAsNRHuVrnatxZYGvYMWwJlzPMJrZj
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
VUMAAA==

-->

</rfc>