<?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.13 -->

<!DOCTYPE rfc SYSTEM "../Tools/rfcbootstrap/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 ipr="trust200902" docName="draft-nottingham-link-hint-02" category="info">

  <front>
    <title>HTTP Link Hints</title>

    <author initials="M." surname="Nottingham" fullname="Mark Nottingham">
      <organization></organization>
      <address>
        <email>mnot@mnot.net</email>
        <uri>https://www.mnot.net/</uri>
      </address>
    </author>

    <date year="2020"/>

    <area>General</area>
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This memo specifies “HTTP Link Hints”, a mechanism for annotating Web links to HTTP(S) resources with information that otherwise might be discovered by interacting with them.</t>



    </abstract>


    <note title="Note to Readers">


<t><spanx style="emph">RFC EDITOR: please remove this section before publication</spanx></t>

<t>The issues list for this draft can be found at <eref target="https://github.com/mnot/I-D/labels/link-hint">https://github.com/mnot/I-D/labels/link-hint</eref>.</t>

<t>The most recent (often, unpublished) draft is at <eref target="https://mnot.github.io/I-D/link-hint/">https://mnot.github.io/I-D/link-hint/</eref>.</t>

<t>Recent changes are listed at <eref target="https://github.com/mnot/I-D/commits/gh-pages/link-hint">https://github.com/mnot/I-D/commits/gh-pages/link-hint</eref>.</t>

<t>See also the draft’s current status in the IETF datatracker, at <eref target="https://datatracker.ietf.org/doc/draft-nottingham-link-hint/">https://datatracker.ietf.org/doc/draft-nottingham-link-hint/</eref>.</t>


    </note>


  </front>

  <middle>


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

<t>HTTP <xref target="RFC7230"/> clients can discover a variety of information about a resource by interacting with it. For example, the methods supported can be learned through the Allow response header field, and the need for authentication is conveyed with a 401 Authentication Required status code.</t>

<t>Often, it can be beneficial to know this information before interacting with the resource; not only can such knowledge save time (through reduced round trips), but it can also affect the choices available to the code or user driving the interaction.</t>

<t>For example, a user interface that presents the data from an HTTP-based API might need to know which resources the user has write access to, so that it can present the appropriate interface.</t>

<t>This specification defines a vocabulary of “HTTP link hints” that allow such metadata about HTTP resources to be attached to Web links <xref target="RFC8288"/>, thereby making it available before the link is followed. It also establishes a registry for future hints.</t>

<t>Hints are just that – they are not a “contract”, and are to only be taken as advisory. The runtime behaviour of the resource always overrides hinted information.</t>

<t>For example, a client might receive a hint that the PUT method is allowed on all “widget” resources. This means that generally, the client can PUT to them, but a specific resource might reject a PUT based upon access control or other considerations.</t>

<t>More fine-grained information might also be gathered by interacting with the resource (e.g., via a GET), or by another resource “containing” it (such as a “widgets” collection) or describing it (e.g., one linked to it with a “describedby” link relation).</t>

<t>There is not a single way to carry hints in a link; rather, it is expected that this will be done by individual link serialisations (see <xref target="RFC8288"/>, Section 3.4.1). However, <xref target="link_header"/> does recommend how to include link hints in the existing Link HTTP header field.</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>

</section>
</section>
<section anchor="link_hints" title="HTTP Link Hints">

<t>A HTTP link hint is a (key, value) tuple that describes the target resource of a Web link <xref target="RFC8288"/>, or the link itself. The value’s canonical form is a JSON <xref target="RFC8259"/> data structure specific to that hint.</t>

<t>Typically, link hints are serialised in links as target attributes (<xref target="RFC8288"/>, Section 3.4.1).</t>

<t>In JSON-based formats, this can be achieved by simply serialising link hints as an object; for example:</t>

<figure><artwork><![CDATA[
{
  "_links": {
    "self": {
      "href": "/orders/523",
       "hints": {
        "allow": ["GET", "POST"],
        "accept-post": {
          "application/example+json":
            {}
        }
      }
    }
  }
}
]]></artwork></figure>

<t>In other link formats, this requires a mapping from the canonical JSON data model. One such mapping is described in <xref target="link_header"/> for the Link HTTP header field.</t>

<t>The information in a link hint SHOULD NOT be considered valid for longer than the freshness lifetime (<xref target="RFC7234"/>, Section 4.2) of the representation that the link occurred within, and in some cases, it might be valid for a considerably shorter period.</t>

<t>Likewise, the information in a link hint is specific to the link it is attached to. This means that if a representation is specific to a particular user, the hints on links in that representation are also specific to that user.</t>

</section>
<section anchor="hints" title="Pre-Defined HTTP Link Hints">

<section anchor="allow" title="allow">

<t><list style="symbols">
  <t>Hint Name: allow</t>
  <t>Description: Hints the HTTP methods that can be used to interact with the target resource; equivalent to the Allow HTTP response header.</t>
  <t>Content Model: array (of strings)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing HTTP methods (<xref target="RFC7231"/>, Section 4).</t>

</section>
<section anchor="formats" title="formats">

<t><list style="symbols">
  <t>Hint Name: formats</t>
  <t>Description: Hints the representation type(s) that the target resource can produce and consume, using the GET and PUT (if allowed) methods respectively.</t>
  <t>Content Model: object</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an object, whose keys are media types (<xref target="RFC7231"/>, Section 3.1.1.1), and values are objects.</t>

<t>The object MAY have a “links” member, whose value is an object representing links (in the sense of <xref target="RFC8288"/>) whose context is any document that uses that format. Generally, this will be schema or profile (<xref target="RFC6906"/>) information. The “links” member has the same format as the “links” hint.</t>

<t>Furthermore, the object MAY have a “deprecated” member, whose value is either true or false, indicating whether support for the format might be removed in the near future.</t>

<t>All other members of the object are under control of the corresponding media type’s definition.</t>

</section>
<section anchor="links" title="links">

<t><list style="symbols">
  <t>Hint Name: links</t>
  <t>Description: Hints at links whose context is the target resource.</t>
  <t>Content Model: object</t>
  <t>Specification: [this document]</t>
</list></t>

<t>The “links” hint contains links (in the sense of <xref target="RFC8288"/>) whose context is the hinted target resource, which are stable for the lifetime of the hint.</t>

<t>Content MUST be an object, whose member names are link relations (<xref target="RFC8288"/>) and values are objects that MUST have an “href” member whose value is a URI-reference (<xref target="RFC3986"/>, using the original link as the base for resolution) for the link hint’s target resource, and MAY itself contain link hints, serialised as the value for a “hints” member.</t>

<t>For example:</t>

<figure><artwork><![CDATA[
"links": {
  "edit-form": {
    "href": "./edit",
    "hints": {
      formats: {
        "application/json": {}
      }
    }
  }
}
]]></artwork></figure>

</section>
<section anchor="accept-post" title="accept-post">

<t><list style="symbols">
  <t>Hint Name: accept-post</t>
  <t>Description: Hints the POST request format(s) that the target resource can consume.</t>
  <t>Content Model: object</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an object, with the same constraints as for “formats”.</t>

<t>When this hint is present, “POST” SHOULD be listed in the “allow” hint.</t>

</section>
<section anchor="accept-patch" title="accept-patch">

<t><list style="symbols">
  <t>Hint Name: accept-patch</t>
  <t>Description: Hints the PATCH <xref target="RFC5789"/> request format(s) that the target resource can consume; equivalent to the Accept-Patch HTTP response header.</t>
  <t>Content Model: array (of strings)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing media types (<xref target="RFC7231"/>, Section 3.1.1.1).</t>

<t>When this hint is present, “PATCH” SHOULD be listed in the “allow” hint.</t>

</section>
<section anchor="accept-ranges" title="accept-ranges">

<t><list style="symbols">
  <t>Hint Name: accept-ranges</t>
  <t>Description: Hints the range-specifier(s) available for the target resource; equivalent to the Accept-Ranges HTTP response header <xref target="RFC7233"/>.</t>
  <t>Content Model: array (of strings)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing HTTP range-specifiers (<xref target="RFC7233"/>, Section 3.1).</t>

</section>
<section anchor="accept-prefer" title="accept-prefer">

<t><list style="symbols">
  <t>Hint Name: accept-prefer</t>
  <t>Description: Hints the preference(s) <xref target="RFC7240"/> that the target resource understands (and might act upon) in requests.</t>
  <t>Content Model: array (of strings)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, contain preferences (<xref target="RFC7240"/>, Section 2). Note that, by its nature, a preference can be ignored by the server.</t>

</section>
<section anchor="precondition-req" title="precondition-req">

<t><list style="symbols">
  <t>Hint Name: precondition-req</t>
  <t>Description: Hints that the target resource requires state-changing requests (e.g., PUT, PATCH) to include a precondition, as per <xref target="RFC7232"/>, to avoid conflicts due to concurrent updates.</t>
  <t>Content Model: array (of strings)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, with possible values “etag” and “last-modified” indicating type of precondition expected.</t>

<t>See also the 428 Precondition Required status code (<xref target="RFC6585"/>).</t>

</section>
<section anchor="auth-schemes" title="auth-schemes">

<t><list style="symbols">
  <t>Hint Name: auth-schemes</t>
  <t>Description: Hints that the target resource requires authentication using the HTTP Authentication Framework <xref target="RFC7235"/>.</t>
  <t>Content Model: array (of objects)</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of objects, each with a “scheme” member containing a string that corresponds to a HTTP authentication scheme (<xref target="RFC7235"/>), and optionally a “realms” member containing an array of zero to many strings that identify protection spaces that the resource is a member of.</t>

<t>For example:</t>

<figure><artwork><![CDATA[
  {
    "auth-req": [
      {
        "scheme": "Basic",
        "realms": ["private"]
      }
    ]
  }
]]></artwork></figure>

</section>
<section anchor="status" title="status">

<t><list style="symbols">
  <t>Hint Name: status</t>
  <t>Description: Hints the status of the target resource.</t>
  <t>Content Model: string</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be a string; possible values are:</t>

<t><list style="symbols">
  <t>“deprecated” - indicates that use of the resource is not recommended, but it is still available.</t>
  <t>“gone” - indicates that the resource is no longer available; i.e., it will return a 410 Gone HTTP status code if accessed.</t>
</list></t>

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

<t>Clients need to exercise care when using hints. For example, a naive client might send credentials to a server that uses the auth-req hint, without checking to see if those credentials are appropriate for that server.</t>

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

<section anchor="hint_registry" title="HTTP Link Hint Registry">

<t>This specification defines the HTTP Link Hint Registry. See <xref target="link_hints"/> for a general description of the function of link hints.</t>

<t>Link hints are generic; that is, they are potentially applicable to any HTTP resource, not specific to one application of HTTP, nor to one particular format. Generally, they ought to be information that would otherwise be discoverable by interacting with the resource.</t>

<t>Hint names MUST be composed of the lowercase letters (a-z), digits (0-9), underscores (“_”) and hyphens (“-“), and MUST begin with a lowercase letter.</t>

<t>Hint content MUST be described in terms of JSON values (<xref target="RFC8259"/>, Section 3).</t>

<t>Hint semantics SHOULD be described in terms of the framework defined in <xref target="RFC8288"/>.</t>

<t>New hints are registered using the Expert Review process described in <xref target="RFC8126"/> to enforce the criteria above. Requests for registration of new resource hints are to use the following template:</t>

<t><list style="symbols">
  <t>Hint Name: [hint name]</t>
  <t>Description: [a short description of the hint’s semantics]</t>
  <t>Content Model: [valid JSON value types; see RFC627 Section 2.1]</t>
  <t>Specification: [reference to specification document]</t>
</list></t>

<t>Initial registrations are enumerated in <xref target="hints"/>. The “rel”, “rev”, “hreflang”, “media”, “title”, and “type” hint names are reserved, so as to avoid potential clashes with link serialisations.</t>

</section>
</section>


  </middle>

  <back>

    <references title='Normative References'>





<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>



<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="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="RFC8259" target='https://www.rfc-editor.org/info/rfc8259'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials='T.' surname='Bray' fullname='T. Bray' role='editor'><organization /></author>
<date year='2017' month='December' />
<abstract><t>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.</t><t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract>
</front>
<seriesInfo name='STD' value='90'/>
<seriesInfo name='RFC' value='8259'/>
<seriesInfo name='DOI' value='10.17487/RFC8259'/>
</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="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="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="RFC5789" target='https://www.rfc-editor.org/info/rfc5789'>
<front>
<title>PATCH Method for HTTP</title>
<author initials='L.' surname='Dusseault' fullname='L. Dusseault'><organization /></author>
<author initials='J.' surname='Snell' fullname='J. Snell'><organization /></author>
<date year='2010' month='March' />
<abstract><t>Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification.  The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5789'/>
<seriesInfo name='DOI' value='10.17487/RFC5789'/>
</reference>



<reference  anchor="RFC7233" target='https://www.rfc-editor.org/info/rfc7233'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Range Requests</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='Y.' surname='Lafon' fullname='Y. Lafon' 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 range requests and the rules for constructing and combining responses to those requests.</t></abstract>
</front>
<seriesInfo name='RFC' value='7233'/>
<seriesInfo name='DOI' value='10.17487/RFC7233'/>
</reference>



<reference  anchor="RFC7240" target='https://www.rfc-editor.org/info/rfc7240'>
<front>
<title>Prefer Header for HTTP</title>
<author initials='J.' surname='Snell' fullname='J. Snell'><organization /></author>
<date year='2014' month='June' />
<abstract><t>This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.</t></abstract>
</front>
<seriesInfo name='RFC' value='7240'/>
<seriesInfo name='DOI' value='10.17487/RFC7240'/>
</reference>



<reference  anchor="RFC7232" target='https://www.rfc-editor.org/info/rfc7232'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</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 HTTP/1.1 conditional requests, including metadata header fields for indicating state changes, request header fields for making preconditions on such state, and rules for constructing the responses to a conditional request when one or more preconditions evaluate to false.</t></abstract>
</front>
<seriesInfo name='RFC' value='7232'/>
<seriesInfo name='DOI' value='10.17487/RFC7232'/>
</reference>



<reference  anchor="RFC6585" target='https://www.rfc-editor.org/info/rfc6585'>
<front>
<title>Additional HTTP Status Codes</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<date year='2012' month='April' />
<abstract><t>This document specifies additional HyperText Transfer Protocol (HTTP) status codes for a variety of common situations.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6585'/>
<seriesInfo name='DOI' value='10.17487/RFC6585'/>
</reference>



<reference  anchor="RFC7235" target='https://www.rfc-editor.org/info/rfc7235'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Authentication</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, hypermedia information systems.  This document defines the HTTP Authentication framework.</t></abstract>
</front>
<seriesInfo name='RFC' value='7235'/>
<seriesInfo name='DOI' value='10.17487/RFC7235'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor="RFC6906" target='https://www.rfc-editor.org/info/rfc6906'>
<front>
<title>The 'profile' Link Relation Type</title>
<author initials='E.' surname='Wilde' fullname='E. Wilde'><organization /></author>
<date year='2013' month='March' />
<abstract><t>This specification defines the 'profile' link relation type that allows resource representations to indicate that they are following one or more profiles.  A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms.</t></abstract>
</front>
<seriesInfo name='RFC' value='6906'/>
<seriesInfo name='DOI' value='10.17487/RFC6906'/>
</reference>



<reference  anchor="RFC8126" target='https://www.rfc-editor.org/info/rfc8126'>
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials='M.' surname='Cotton' fullname='M. Cotton'><organization /></author>
<author initials='B.' surname='Leiba' fullname='B. Leiba'><organization /></author>
<author initials='T.' surname='Narten' fullname='T. Narten'><organization /></author>
<date year='2017' month='June' />
<abstract><t>Many protocols make use of points of extensibility that use constants to identify various protocol parameters.  To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper.  For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA).</t><t>To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed.  This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.</t><t>This is the third edition of this document; it obsoletes RFC 5226.</t></abstract>
</front>
<seriesInfo name='BCP' value='26'/>
<seriesInfo name='RFC' value='8126'/>
<seriesInfo name='DOI' value='10.17487/RFC8126'/>
</reference>




    </references>


<section anchor="link_header" title="Representing Link Hints in Link Headers">

<t>A link hint can be represented in a Link header (<xref target="RFC8288"/>, Section 3) as a link-extension.</t>

<t>When doing so, the JSON of the hint’s content SHOULD be normalised to reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are part of a string value, these characters MUST be escaped as described in <xref target="RFC8259"/> Section 7; otherwise, they MUST be discarded.</t>

<t>Furthermore, if the content is an array or an object, the surrounding delimiters MUST be removed before serialisation. In other words, the outermost object or array is represented without the braces (“{}”) or brackets (“[]”) respectively, but this does not apply to inner objects or arrays.</t>

<t>For example, the two JSON values below are those of the fictitious “example” and “example1” hints, respectively:</t>

<figure><artwork><![CDATA[
"The Example Value"
1.2
]]></artwork></figure>

<t>In a Link header, they would be serialised as:</t>

<figure><artwork><![CDATA[
Link: </>; rel="sample"; example="The Example Value";
      example1=1.2
]]></artwork></figure>

<t>A more complex, single value for “example”:</t>

<figure><artwork><![CDATA[
[
  "foo",
  -1.23,
  true,
  ["charlie", "bennet"],
  {"cat": "thor"},
  false
]
]]></artwork></figure>

<t>would be serialised as:</t>

<figure><artwork><![CDATA[
Link: </>; rel="sample"; example="\"foo\", -1.23, true,
      [\"charlie\", \"bennet\"], {"cat": \"thor\"}, false"
]]></artwork></figure>

</section>
<section anchor="acknowledgements" title="Acknowledgements">

<t>Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their suggestions and feedback.</t>

</section>


  </back>

<!-- ##markdown-source:
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

-->

</rfc>

