Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
393 lines (235 sloc) 12 KB
Network Working Group I. Nadareishvili
Internet-Draft
Intended status: Informational E. Wilde
Expires: July 22, 2018 January 18, 2018
Transclude Preference for the HTTP Prefer Header
inadarei-prefer-transclude
Abstract
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.
Note to Readers
*RFC EDITOR: please remove this section before publication*
The issues list for this draft can be found at
https://github.com/inadarei/draft-prefer-transclude/issues [1].
The most recent draft is at https://inadarei.github.io/draft-prefer-
transclude/ [2].
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 22, 2018.
Nadareishvili & Wilde Expires July 22, 2018 [Page 1]
Internet-Draft Transclude for HTTP Prefer January 2018
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3. Transclude Usage Example . . . . . . . . . . . . . . . . . . 3
4. Implementation Considerations . . . . . . . . . . . . . . . . 4
5. Multipart Response Example . . . . . . . . . . . . . . . . . 4
6. Security Considerations . . . . . . . . . . . . . . . . . . . 5
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
8.1. Normative References . . . . . . . . . . . . . . . . . . 6
8.2. Informative References . . . . . . . . . . . . . . . . . 6
8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 7
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction
"Prefer Header for HTTP" [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.
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
Nadareishvili & Wilde Expires July 22, 2018 [Page 2]
Internet-Draft Transclude for HTTP Prefer January 2018
instance: to only send mobile app a minimal response when it doesn't
need full resource.
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.
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.
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
[RFC8288].
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.
2. Notational Conventions
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 [RFC2119].
3. Transclude Usage Example
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.
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
Nadareishvili & Wilde Expires July 22, 2018 [Page 3]
Internet-Draft Transclude for HTTP Prefer January 2018
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 [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.
Example response may look something like the following:
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
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.
4. Implementation Considerations
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.
5. Multipart Response Example
Nadareishvili & Wilde Expires July 22, 2018 [Page 4]
Internet-Draft Transclude for HTTP Prefer January 2018
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--
6. Security Considerations
Specific resources transcluded by a client can introduce security
considerations and concerns beyond those discussed within Prefer
Header for HTTP [RFC7240], or HTTP/1.1 [RFC7230] and its associated
specification documents (see [RFC7230] for the list of associated
works). Implementers need to consider implications of including
supported media types and implement appropriate security measures.
Nadareishvili & Wilde Expires July 22, 2018 [Page 5]
Internet-Draft Transclude for HTTP Prefer January 2018
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.
7. IANA Considerations
The HTTP Preference below is being registered with IANA per
Section 5.1 of [RFC7240]:
Preference: transclude Value: Optional Parameters: Description:
Reference: RFC XXXX
8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,
DOI 10.17487/RFC7240, June 2014,
<https://www.rfc-editor.org/info/rfc7240>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>.
8.2. Informative References
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>.
8.3. URIs
[1] https://github.com/inadarei/draft-prefer-transclude/issues
[2] https://inadarei.github.io/draft-prefer-transclude/
Nadareishvili & Wilde Expires July 22, 2018 [Page 6]
Internet-Draft Transclude for HTTP Prefer January 2018
Appendix A. Acknowledgments
Authors' Addresses
Irakli Nadareishvili
114 5th Avenue
New York
United States
Email: irakli@gmail.com
URI: http://www.freshblurbs.com/
Erik Wilde
Email: erik.wilde@dret.net
URI: http://dret.net/netdret/
Nadareishvili & Wilde Expires July 22, 2018 [Page 7]