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.

The most recent draft is at https://inadarei.github.io/draft-prefer-transclude/.

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.

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. Notational Conventions
• 3. Transclude Usage Example
• 4. Implementation Considerations
• 5. Multipart Response Example
• 6. Security Considerations
• 7. IANA Considerations
• 8. References
• 8.1. Normative References
• 8.2. Informative References
• Appendix A. Acknowledgments
• Authors' Addresses

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

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

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.

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

8.2. Informative References

Appendix A. Acknowledgments

Authors' Addresses