draft-inadarei-prefer-transclude-00.txt

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]