Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
418 lines (322 sloc) 16.7 KB
<?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.7 -->
<!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 ipr="trust200902" docName="inadarei-prefer-transclude" category="info">
<front>
<title abbrev="Transclude for HTTP Prefer">Transclude Preference for the HTTP Prefer Header</title>
<author initials="I." surname="Nadareishvili" fullname="Irakli Nadareishvili">
<organization></organization>
<address>
<postal>
<street>114 5th Avenue</street>
<city>New York</city>
<country>United States</country>
</postal>
<email>irakli@gmail.com</email>
<uri>http://www.freshblurbs.com/</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="2018"/>
<area>General</area>
<keyword>Internet-Draft</keyword>
<abstract>
<t>The Transclude preference is a registered behavior for the HTTP Prefer header
field. Its purpose is for clients to specify preferences that certain links in
a response should be resolved by the server, instead of being served as links
that the client can resolve.</t>
</abstract>
<note title="Note to Readers">
<t><spanx style="strong">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/inadarei/draft-prefer-transclude/issues">https://github.com/inadarei/draft-prefer-transclude/issues</eref>.</t>
<t>The most recent draft is at <eref target="https://inadarei.github.io/draft-prefer-transclude/">https://inadarei.github.io/draft-prefer-transclude/</eref>.</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>“Prefer Header for HTTP” <xref target="RFC7240"/> defines an HTTP header that can be used
to indicate that particular server behaviors are preferred by the client but
are not required for successful completion of the request. It further defines
several standard Preferences, such as the “return” preference. The “return”
preference lets the server know that the client would prefer a specific
representation of a resource in a response payload, e.g. full representation
vs. a minimal one.</t>
<t>Preferences like the “return” one are critical for mobile scenarios as mobile
applications are very sensitive to network latency, throughput and anything
that can improve end-user experience, even on resource-constrained networks.
Prefer header allows servers to tune and optimize its response payload based
on client preferences, for instance: to only send mobile app a minimal response
when it doesn’t need full resource.</t>
<t>The size of the payload is not the only preference that can improve
user-experience in mobile scenarios, however. Closely related to the size of
the payload, is the number of HTTP requests a client needs to make to get all
of the required data. This is the challenge that “transclude” preference
addresses.</t>
<t>When server sends hypermedia responses (e.g. in the case of hypermedia APIs)
some of the response data may be referenced via a URI link instead of being
embedded in the payload itself. The need to grab data from a link can degrade
experience of mobile applications, since they are forced to make multiple
requests to per single end-user request. This is sometimes referred to as
“chatty interface” and is a significant problem for mobile and Internet of
Things scenarios.</t>
<t>Transclude preference notifies the server that the client would prefer the
server to proactively transclude certain content represented by links of
indicated link relation types. The notion of “link relation type”, in this
context is as defined by Web Linking <xref target="RFC8288"/>.</t>
<t>As a result of using a transclude preference, a client receives all of the
required data already embedded in the response output, without the need to make
additional network calls.</t>
</section>
<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 anchor="transclude-usage-example" title="Transclude Usage Example">
<t>Following is an example of a client asking server to transclude data represented
at the copyright, edit-form and “other-form” links. Since “other-form” is not
a registered IANA link relation type, the client is using a URI for identifying
the extension link relation type.</t>
<figure><artwork><![CDATA[
Get /blog/1223 HTTP/1.1
Host: api.example.org
Content-Type: application/json
Prefer: transclude="copyright;edit-form;http://rels.io/other-form"
Vary: Prefer,Accept,Accept-Encoding
]]></artwork></figure>
<t>As can be seen from the example, the transclude preference expects the value
to be enclosed in double quotes, if there are multiple link relation types
provided. As required by Web Linking <xref target="RFC8288"/>, registered link relations
MUST be indicated by a simple string, while extension link relation types MUST
be indicated with a unique URI representing that link relation. Multiple link
relation types MUST be separated by semicolon.</t>
<t>Example response may look something like the following:</t>
<figure><artwork><![CDATA[
HTTP/1.1 200 OK
Server: nginx/1.10.3 (Ubuntu)
Date: Sat, 27 Jun 2017 10:07:32 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: close
Vary: Prefer,Accept,Accept-Encoding
Preference-Applied: transclude="copyright;edit-form"
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type
]]></artwork></figure>
<t>As can be seen from this output, the server only transcluded copyright and
edit-form link relation types, but not the custom type client requested. This
is because preferences are just suggestions and server has no obligation related
to them. In this case, we can assume that the server skipped the last link
relation type because maybe it was not familiar with it, or for some other
reason.</t>
</section>
<section anchor="implementation-considerations" title="Implementation Considerations">
<t>Transclude preference is media-type agnostic. It should work with any response
content-type. The mechanics of transclusion, however will either depend on
capabilities of the response media-type or require a multi-part response with
multiple media types in the response.</t>
</section>
<section anchor="multipart-response-example" title="Multipart Response Example">
<figure><artwork><![CDATA[
HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 15 Sep 2017 11:07:32 GMT
Content-type: multipart/mixed; boundary="some boundary string"
--some boundary string
Content-Type: application/hal+json; charset=utf-8
{
"_links": {
"self": { "href": "/orders" },
"edit-form": { "href": "/create" }
},
"currentlyProcessing": 14,
"shippedToday": 20
}
--some boundary string
Content-Type: application/prs.hal-forms+json
{
"_links" : {
"self" : { "href" : "/create" }
},
"_templates" : {
"default" : {
"title" : "Create",
"method" : "post",
"contentType" : "application/json",
"properties" : [
{"name": "title", "required": true,
"prompt": "Title"},
{"name": "completed", "value": "false",
"prompt": "Completed"}
]
}
}
}
--some boundary string--
]]></artwork></figure>
</section>
<section anchor="security-considerations" title="Security Considerations">
<t>Specific resources transcluded by a client can introduce security
considerations and concerns beyond those discussed within Prefer Header for
HTTP <xref target="RFC7240"/>, or HTTP/1.1 <xref target="RFC7230"/> and its associated specification
documents (see <xref target="RFC7230"/> for the list of associated works). Implementers
need to consider implications of including supported media types and implement
appropriate security measures.</t>
<t>A server could incur greater costs in attempting to comply with a
transclusion preference. Unconditional compliance from a server could
allow the use of preferences for denial of service. A server can
ignore an expressed preference to avoid expending resources that it
does not wish to commit.</t>
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<t>The HTTP Preference below is being registered with IANA per Section 5.1 of
<xref target="RFC7240"/>:</t>
<t>Preference: transclude
Value:
Optional Parameters:
Description:
Reference: RFC XXXX</t>
</section>
</middle>
<back>
<references title='Normative References'>
<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="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>
</references>
<references title='Informative 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>
</references>
<section anchor="acknowledgments" title="Acknowledgments">
</section>
</back>
<!-- ##markdown-source:
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
Ff8Dd5+6O/YdAAA=
-->
</rfc>