One document matched: draft-nottingham-link-hint-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../Tools/rfc2629xslt/rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "../Tools/rfc2629xslt/rfc2629.dtd">
<rfc ipr="trust200902" docName="draft-nottingham-link-hint-00" category="info">
<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<front>
<title>HTTP Link Hints</title>
<author initials="M." surname="Nottingham" fullname="Mark Nottingham">
<organization/>
<address>
<email>mnot@mnot.net</email>
<uri>http://www.mnot.net/</uri>
</address>
</author>
<date year="2013"/>
<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>This draft should be discussed on the apps-discuss mailing list; see
<xref target="apps-discuss"/>.</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>Clients can discover a variety of information about a HTTP
<xref target="I-D.ietf-httpbis-p1-messaging"/> resource by interacting with it. For
example, the methods supported can be learned through the Allow response header
field, whereas the need for authentication is conveyed with a 401
Authentication Required status code.</t>
<t>In some situations, it can be beneficial to know this information before
interacting with the resource; not only can it save time (through reduced round
trips), but it can also affect the choices given 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="RFC5988"/>, thereby
making it available before the link is followed. It also establishes a registry
for future hints.</t>
<t>It does not recommend a single serialisation format for link hints; rather, it
is expected that this will be done by individual link serialisations that use
hints (whether they be in a representation body, message headers or elsewhere). However, <xref target="link_header"/> does recommend how to include link hints in the
existing Link HTTP header field.</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 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>
<section anchor="notational-conventions" title="Notational Conventions">
<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in <xref target="RFC2119"/>.</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="RFC5988"/>, or the link itself. The value’s canonical form is a
JSON <xref target="RFC4627"/> data structure, whose form is defined by the hint’s
definition. </t>
<t>Typically, they are serialised in links as target attributes.</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 for the Link HTTP header is described in
<xref target="link_header"/>.</t>
<t>The information in a link hint SHOULD NOT be considered valid for longer than
the freshness lifetime (<xref target="I-D.ietf-httpbis-p6-cache"/>) 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.</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, 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="RFC5988"/>) 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="RFC5988"/>) 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="RFC5988"/>)
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. Note that there is
no opportunity to communicate format-specific hints for PATCH formats.</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="I-D.ietf-httpbis-p5-range"/>.</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.</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="I-D.snell-http-prefer"/> 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. 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="I-D.ietf-httpbis-p4-conditional"/>, 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="I-D.ietf-httpbis-p7-auth"/>.</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, 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="RFC4627"/>, Section
2.1).</t>
<t>Hint semantics SHOULD be described in terms of the framework defined in
<xref target="RFC5988"/>.</t>
<t>New hints are registered using the Expert Review process described in
<xref target="RFC5226"/> 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="RFC2119">
<front>
<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="Scott Bradner">
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street>
</postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email>
</address>
</author>
<date year="1997" month="March"/>
<area>General</area>
<keyword>keyword</keyword>
<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. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
<list><t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
</t></list></t>
<t>
Note that the force of these words is modified by the requirement
level of the document in which they are used.
</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<format type="TXT" octets="4723" target="http://www.rfc-editor.org/rfc/rfc2119.txt"/>
<format type="HTML" octets="17970" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/>
<format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/>
</reference>
<reference anchor="RFC3986">
<front>
<title abbrev="URI Generic Syntax">Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
<organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
<address>
<postal>
<street>Massachusetts Institute of Technology</street>
<street>77 Massachusetts Avenue</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code>
<country>USA</country>
</postal>
<phone>+1-617-253-5702</phone>
<facsimile>+1-617-258-5999</facsimile>
<email>timbl@w3.org</email>
<uri>http://www.w3.org/People/Berners-Lee/</uri>
</address>
</author>
<author initials="R." surname="Fielding" fullname="Roy T. Fielding">
<organization abbrev="Day Software">Day Software</organization>
<address>
<postal>
<street>5251 California Ave., Suite 110</street>
<city>Irvine</city>
<region>CA</region>
<code>92617</code>
<country>USA</country>
</postal>
<phone>+1-949-679-2960</phone>
<facsimile>+1-949-679-2972</facsimile>
<email>fielding@gbiv.com</email>
<uri>http://roy.gbiv.com/</uri>
</address>
</author>
<author initials="L." surname="Masinter" fullname="Larry Masinter">
<organization abbrev="Adobe Systems">Adobe Systems Incorporated</organization>
<address>
<postal>
<street>345 Park Ave</street>
<city>San Jose</city>
<region>CA</region>
<code>95110</code>
<country>USA</country>
</postal>
<phone>+1-408-536-3024</phone>
<email>LMM@acm.org</email>
<uri>http://larry.masinter.net/</uri>
</address>
</author>
<date year="2005" month="January"/>
<area>Applications</area>
<keyword>uniform resource identifier</keyword>
<keyword>URI</keyword>
<keyword>URL</keyword>
<keyword>URN</keyword>
<keyword>WWW</keyword>
<keyword>resource</keyword>
<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.
</t>
</abstract>
</front>
<seriesInfo name="STD" value="66"/>
<seriesInfo name="RFC" value="3986"/>
<format type="TXT" octets="141811" target="http://www.rfc-editor.org/rfc/rfc3986.txt"/>
<format type="HTML" octets="214067" target="http://xml.resource.org/public/rfc/html/rfc3986.html"/>
<format type="XML" octets="163534" target="http://xml.resource.org/public/rfc/xml/rfc3986.xml"/>
</reference>
<reference anchor="RFC4627">
<front>
<title>The application/json Media Type for JavaScript Object Notation (JSON)</title>
<author initials="D." surname="Crockford" fullname="D. Crockford">
<organization/>
</author>
<date year="2006" month="July"/>
<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. This memo provides information for the Internet community.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="4627"/>
<format type="TXT" octets="16319" target="http://www.rfc-editor.org/rfc/rfc4627.txt"/>
</reference>
<reference anchor="RFC5226">
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials="T." surname="Narten" fullname="T. Narten">
<organization/>
</author>
<author initials="H." surname="Alvestrand" fullname="H. Alvestrand">
<organization/>
</author>
<date year="2008" month="May"/>
<abstract>
<t>Many protocols make use of identifiers consisting of constants and other well-known values. Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec). To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority. For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).</t><t> In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made. If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role. This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.</t><t> This document obsoletes RFC 2434. 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="26"/>
<seriesInfo name="RFC" value="5226"/>
<format type="TXT" octets="66160" target="http://www.rfc-editor.org/rfc/rfc5226.txt"/>
</reference>
<reference anchor="RFC5988">
<front>
<title>Web Linking</title>
<author initials="M." surname="Nottingham" fullname="M. Nottingham">
<organization/>
</author>
<date year="2010" month="October"/>
<abstract>
<t>This document specifies relation types for Web links, and defines a registry for them. It also defines the use of such links in HTTP headers with the Link header field. [STANDARDS-TRACK]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="5988"/>
<format type="TXT" octets="46834" target="http://www.rfc-editor.org/rfc/rfc5988.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p1-messaging">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. HTTP has been in use by the World Wide Web global information initiative since 1990. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes general security concerns for implementations.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p1-messaging-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-22.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p6-cache">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="M" surname="Nottingham" fullname="Mark Nottingham">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines requirements on HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p6-cache-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p6-cache-22.txt"/>
</reference>
</references>
<references title="Informative References">
<reference anchor="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"/>
<format type="TXT" octets="21706" target="http://www.rfc-editor.org/rfc/rfc5789.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="17164" target="http://www.rfc-editor.org/rfc/rfc6585.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="18469" target="http://www.rfc-editor.org/rfc/rfc6906.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p4-conditional">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an 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="Internet-Draft" value="draft-ietf-httpbis-p4-conditional-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p4-conditional-22.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p5-range">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Range Requests</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="Y" surname="Lafon" fullname="Yves Lafon">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an 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="Internet-Draft" value="draft-ietf-httpbis-p5-range-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p5-range-22.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p7-auth">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Authentication</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p7-auth-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p7-auth-22.txt"/>
</reference>
<reference anchor="I-D.snell-http-prefer">
<front>
<title>Prefer Header for HTTP</title>
<author initials="J" surname="Snell" fullname="James Snell">
<organization/>
</author>
<date month="January" day="7" year="2013"/>
<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="Internet-Draft" value="draft-snell-http-prefer-18"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-snell-http-prefer-18.txt"/>
</reference>
<reference anchor="apps-discuss" target="https://www.ietf.org/mailman/listinfo/apps-discuss">
<front>
<title>IETF Apps-Discuss Mailing List</title>
<author>
<organization>IETF</organization>
</author>
<date year="n.d."/>
</front>
</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="RFC5988"/>, Section 5) 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="RFC4627"/> Section 2.5;
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 “exmaple1” 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>
<section anchor="open-issues" title="Open Issues">
<t>The following is a list of placeholders for open issues.</t>
<t>
<list style="symbols">
<t>Resource Hints
<list style="symbols"><t>indicate a POST to 201 Created pattern</t><t>indicate an “action” POST</t><t>outbound links</t><t>forms?</t></list></t>
<t>Representation Hints
<list style="symbols"><t>format profiles</t><t>schema?</t><t>deprecation</t></list></t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 15:52:27 |