Network Working Group I. Nadareishvili
Internet-Draft September 15, 2016
Intended status: Informational
Expires: March 19, 2017

Transclude Preference for the HTTP Prefer Header


The specification for Transclude preference is an extension to the Prefer Header for HTTP [RFC7240]. It works similar to other preferences defined in [RFC7240], such as: return, respond-async, wait and handling.

Note to Readers

Please discuss this draft on the apps-discuss mailing list (<>).

Online access to all versions and files is available on GitHub (<>).

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

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 March 19, 2017.

Copyright Notice

Copyright (c) 2016 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 ( 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. Requirements notation

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

2. Introduction

"Prefer Header for HTTP" [RFC7240] proposes 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 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 [RFC5988].

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.

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 standard, IANA link relation type, client is using a URI for identifying the link relation type.

Get /blog/1223 HTTP/1.1
Content-Type: application/json  
Prefer: transclude="copyright;edit-form;"
Vary: Prefer,Accept,Accept-Encoding

As you can see from the example, the transclude preference expects the value to be enclosed in double quotes, if there're multiple link relation types provided. Further, standard link relations SHOULD be indicated by name while custom link relation types SHOULD be indicated with a unique URI representing that link relation. Multiple link relation types MUST be separated by semicolons.

Example response may look something like the following:

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Sat, 27 Jun 2015 11:03: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 you can see from this output, server only transcluded copyright and edit-form link relation types, but not the cusotm 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 wasn't 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

HTTP/1.1 200 OK
Server: nginx/1.4.6 (Ubuntu)
Date: Thu, 15 Sep 2016 11:03: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. IANA Considerations


7. Security Considerations


8. Normative References

[RFC2119] Bradner, S., "RFC-2119", RFC 2119, March 1997.
[RFC5988] Nottingham, M., "Web Linking (RFC-5988)", RFC 5988, October 2010.
[RFC7240] Snell, J., "Prefer Header for HTTP (RFC-7240)", RFC 7240, June 2014.

Author's Address

Irakli Nadareishvili URI: