[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                      M. Nottingham
Internet-Draft                                             June 10, 2013
Intended status: Informational
Expires: December 12, 2013


                            HTTP Link Hints
                     draft-nottingham-link-hint-00

Abstract

   This memo specifies "HTTP Link Hints", a mechanism for annotating Web
   links to HTTP(S) resources with information that otherwise might be
   discovered by interacting with them.

Note to Readers

   This draft should be discussed on the apps-discuss mailing list; see
   [apps-discuss].

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 http://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 December 12, 2013.

Copyright Notice

   Copyright (c) 2013 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
   (http://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



Nottingham              Expires December 12, 2013               [Page 1]

Internet-Draft               HTTP Link Hints                   June 2013


   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 . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Notational Conventions . . . . . . . . . . . . . . . . . .  3
   2.  HTTP Link Hints  . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  Pre-Defined HTTP Link Hints  . . . . . . . . . . . . . . . . .  4
     3.1.  allow  . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.2.  formats  . . . . . . . . . . . . . . . . . . . . . . . . .  5
     3.3.  links  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     3.4.  accept-post  . . . . . . . . . . . . . . . . . . . . . . .  6
     3.5.  accept-patch . . . . . . . . . . . . . . . . . . . . . . .  6
     3.6.  accept-ranges  . . . . . . . . . . . . . . . . . . . . . .  7
     3.7.  accept-prefer  . . . . . . . . . . . . . . . . . . . . . .  7
     3.8.  precondition-req . . . . . . . . . . . . . . . . . . . . .  7
     3.9.  auth-schemes . . . . . . . . . . . . . . . . . . . . . . .  7
     3.10. status . . . . . . . . . . . . . . . . . . . . . . . . . .  8
   4.  Security Considerations  . . . . . . . . . . . . . . . . . . .  8
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  8
     5.1.  HTTP Link Hint Registry  . . . . . . . . . . . . . . . . .  8
   6.  References . . . . . . . . . . . . . . . . . . . . . . . . . .  9
     6.1.  Normative References . . . . . . . . . . . . . . . . . . .  9
     6.2.  Informative References . . . . . . . . . . . . . . . . . . 10
   Appendix A.  Representing Link Hints in Link Headers . . . . . . . 11
   Appendix B.  Acknowledgements  . . . . . . . . . . . . . . . . . . 12
   Appendix C.  Open Issues . . . . . . . . . . . . . . . . . . . . . 12
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12




















Nottingham              Expires December 12, 2013               [Page 2]

Internet-Draft               HTTP Link Hints                   June 2013


1.  Introduction

   Clients can discover a variety of information about a HTTP
   [I-D.ietf-httpbis-p1-messaging] resource by interacting with it.  For
   example, the methods supported can be learned through the Allow
   response header field, whereas the need for authentication is
   conveyed with a 401 Authentication Required status code.

   In some situations, it can be beneficial to know this information
   before interacting with the resource; not only can it save time
   (through reduced round trips), but it can also affect the choices
   given to the code or user driving the interaction.

   For example, a user interface that presents the data from an HTTP-
   based API might need to know which resources the user has write
   access to, so that it can present the appropriate interface.

   This specification defines a vocabulary of "HTTP link hints" that
   allow such metadata about HTTP resources to be attached to Web links
   [RFC5988], thereby making it available before the link is followed.
   It also establishes a registry for future hints.

   It does not recommend a single serialisation format for link hints;
   rather, it is expected that this will be done by individual link
   serialisations that use hints (whether they be in a representation
   body, message headers or elsewhere).  However, Appendix A does
   recommend how to include link hints in the existing Link HTTP header
   field.

   Hints are just that - they are not a "contract", and are to only be
   taken as advisory.  The runtime behaviour of the resource always
   overrides hinted information.

   For example, a client might receive a hint that the PUT method is
   allowed on all "widget" resources.  This means that generally, the
   client can PUT to them, but a specific resource might reject a PUT
   based upon access control or other considerations.

   More fine-grained information might be gathered by interacting with
   the resource (e.g., via a GET), or by another resource "containing"
   it (such as a "widgets" collection) or describing it (e.g., one
   linked to it with a "describedby" link relation).

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



Nottingham              Expires December 12, 2013               [Page 3]

Internet-Draft               HTTP Link Hints                   June 2013


2.  HTTP Link Hints

   A HTTP link hint is a (key, value) tuple that describes the target
   resource of a Web link [RFC5988], or the link itself.  The value's
   canonical form is a JSON [RFC4627] data structure, whose form is
   defined by the hint's definition.

   Typically, they are serialised in links as target attributes.

   In JSON-based formats, this can be achieved by simply serialising
   link hints as an object; for example:

   {
     "_links": {
       "self": {
         "href": "/orders/523",
          "hints": {
           "allow": ["GET", "POST"],
           "accept-post": {
             "application/example+json":
               {}
           }
         }
       }
     }
   }

   In other link formats, this requires a mapping from the canonical
   JSON data model.  One such mapping for the Link HTTP header is
   described in Appendix A.

   The information in a link hint SHOULD NOT be considered valid for
   longer than the freshness lifetime ([I-D.ietf-httpbis-p6-cache]) of
   the representation that the link occurred within, and in some cases,
   it might be valid for a considerably shorter period.

   Likewise, the information in a link hint is specific to the link it
   is attached to.  This means that if a representation is specific to a
   particular user, the hints on links in that representation are also
   specific to that user.


3.  Pre-Defined HTTP Link Hints

3.1.  allow






Nottingham              Expires December 12, 2013               [Page 4]

Internet-Draft               HTTP Link Hints                   June 2013


   o  Hint Name: allow
   o  Description: Hints the HTTP methods that can be used to interact
      with the target resource; equivalent to the Allow HTTP response
      header.
   o  Content Model: array (of strings)
   o  Specification: [this document]

   Content MUST be an array of strings, containing HTTP methods.

3.2.  formats

   o  Hint Name: formats
   o  Description: Hints the representation type(s) that the target
      resource can produce and consume, using the GET and PUT (if
      allowed) methods respectively.
   o  Content Model: object
   o  Specification: [this document]

   Content MUST be an object, whose keys are media types, and values are
   objects.

   The object MAY have a "links" member, whose value is an object
   representing links (in the sense of [RFC5988]) whose context is any
   document that uses that format.  Generally, this will be schema or
   profile ([RFC6906]) information.  The "links" member has the same
   format as the "links" hint.

   Furthermore, the object MAY have a "deprecated" member, whose value
   is either true or false, indicating whether support for the format
   might be removed in the near future.

   All other members of the object are under control of the
   corresponding media type's definition.

3.3.  links

   o  Hint Name: links
   o  Description: Hints at links whose context is the target resource.
   o  Content Model: object
   o  Specification: [this document]

   The "links" hint contains links (in the sense of [RFC5988]) whose
   context is the hinted target resource, which are stable for the
   lifetime of the hint.

   Content MUST be an object, whose member names are link relations
   ([RFC5988]) and values are objects that MUST have an "href" member
   whose value is a URI-reference ([RFC3986], using the original link as



Nottingham              Expires December 12, 2013               [Page 5]

Internet-Draft               HTTP Link Hints                   June 2013


   the base for resolution) for the link hint's target resource, and MAY
   itself contain link hints, serialised as the value for a "hints"
   member.

   For example:

   "links": {
     "edit-form": {
       "href": "./edit",
       "hints": {
         formats: {
           "application/json": {}
         }
       }
     }
   }

3.4.  accept-post

   o  Hint Name: accept-post
   o  Description: Hints the POST request format(s) that the target
      resource can consume.
   o  Content Model: object
   o  Specification: [this document]

   Content MUST be an object, with the same constraints as for
   "formats".

   When this hint is present, "POST" SHOULD be listed in the "allow"
   hint.

3.5.  accept-patch

   o  Hint Name: accept-patch
   o  Description: Hints the PATCH [RFC5789] request format(s) that the
      target resource can consume; equivalent to the Accept-Patch HTTP
      response header.
   o  Content Model: array (of strings)
   o  Specification: [this document]

   Content MUST be an array of strings, containing media types.  Note
   that there is no opportunity to communicate format-specific hints for
   PATCH formats.

   When this hint is present, "PATCH" SHOULD be listed in the "allow"
   hint.





Nottingham              Expires December 12, 2013               [Page 6]

Internet-Draft               HTTP Link Hints                   June 2013


3.6.  accept-ranges

   o  Hint Name: accept-ranges
   o  Description: Hints the range-specifier(s) available for the target
      resource; equivalent to the Accept-Ranges HTTP response header
      [I-D.ietf-httpbis-p5-range].
   o  Content Model: array (of strings)
   o  Specification: [this document]

   Content MUST be an array of strings, containing HTTP range-
   specifiers.

3.7.  accept-prefer

   o  Hint Name: accept-prefer
   o  Description: Hints the preference(s) [I-D.snell-http-prefer] that
      the target resource understands (and might act upon) in requests.
   o  Content Model: array (of strings)
   o  Specification: [this document]

   Content MUST be an array of strings, contain preferences.  Note that,
   by its nature, a preference can be ignored by the server.

3.8.  precondition-req

   o  Hint Name: precondition-req
   o  Description: Hints that the target resource requires state-
      changing requests (e.g., PUT, PATCH) to include a precondition, as
      per [I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to
      concurrent updates.
   o  Content Model: array (of strings)
   o  Specification: [this document]

   Content MUST be an array of strings, with possible values "etag" and
   "last-modified" indicating type of precondition expected.

   See also the 428 Precondition Required status code ([RFC6585]).

3.9.  auth-schemes

   o  Hint Name: auth-schemes
   o  Description: Hints that the target resource requires
      authentication using the HTTP Authentication Framework
      [I-D.ietf-httpbis-p7-auth].
   o  Content Model: array (of objects)
   o  Specification: [this document]

   Content MUST be an array of objects, each with a "scheme" member



Nottingham              Expires December 12, 2013               [Page 7]

Internet-Draft               HTTP Link Hints                   June 2013


   containing a string that corresponds to a HTTP authentication scheme,
   and optionally a "realms" member containing an array of zero to many
   strings that identify protection spaces that the resource is a member
   of.

   For example:

     {
       "auth-req": [
         {
           "scheme": "Basic",
           "realms": ["private"]
         }
       ]
     }

3.10.  status

   o  Hint Name: status
   o  Description: Hints the status of the target resource.
   o  Content Model: string
   o  Specification: [this document]

   Content MUST be a string; possible values are:

   o  "deprecated" - indicates that use of the resource is not
      recommended, but it is still available.
   o  "gone" - indicates that the resource is no longer available; i.e.,
      it will return a 410 Gone HTTP status code if accessed.


4.  Security Considerations

   Clients need to exercise care when using hints.  For example, a naive
   client might send credentials to a server that uses the auth-req
   hint, without checking to see if those credentials are appropriate
   for that server.


5.  IANA Considerations

5.1.  HTTP Link Hint Registry

   This specification defines the HTTP Link Hint Registry.  See
   Section 2 for a general description of the function of link hints.

   Link hints are generic; that is, they are potentially applicable to
   any HTTP resource, not specific to one application of HTTP, nor to



Nottingham              Expires December 12, 2013               [Page 8]

Internet-Draft               HTTP Link Hints                   June 2013


   one particular format.  Generally, they ought to be information that
   would otherwise be discoverable by interacting with the resource.

   Hint names MUST be composed of the lowercase letters (a-z), digits
   (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
   lowercase letter.

   Hint content MUST be described in terms of JSON values ([RFC4627],
   Section 2.1).

   Hint semantics SHOULD be described in terms of the framework defined
   in [RFC5988].

   New hints are registered using the Expert Review process described in
   [RFC5226] to enforce the criteria above.  Requests for registration
   of new resource hints are to use the following template:

   o  Hint Name: [hint name]
   o  Description: [a short description of the hint's semantics]
   o  Content Model: [valid JSON value types; see RFC627 Section 2.1]
   o  Specification: [reference to specification document]

   Initial registrations are enumerated in Section 3.  The "rel", "rev",
   "hreflang", "media", "title", and "type" hint names are reserved, so
   as to avoid potential clashes with link serialisations.


6.  References

6.1.  Normative References

   [I-D.ietf-httpbis-p1-messaging]
              Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing",
              draft-ietf-httpbis-p1-messaging-22 (work in progress),
              February 2013.

   [I-D.ietf-httpbis-p6-cache]
              Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
              Transfer Protocol (HTTP/1.1): Caching",
              draft-ietf-httpbis-p6-cache-22 (work in progress),
              February 2013.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,



Nottingham              Expires December 12, 2013               [Page 9]

Internet-Draft               HTTP Link Hints                   June 2013


              RFC 3986, January 2005.

   [RFC4627]  Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

6.2.  Informative References

   [I-D.ietf-httpbis-p4-conditional]
              Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Conditional Requests",
              draft-ietf-httpbis-p4-conditional-22 (work in progress),
              February 2013.

   [I-D.ietf-httpbis-p5-range]
              Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
              Transfer Protocol (HTTP/1.1): Range Requests",
              draft-ietf-httpbis-p5-range-22 (work in progress),
              February 2013.

   [I-D.ietf-httpbis-p7-auth]
              Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-22
              (work in progress), February 2013.

   [I-D.snell-http-prefer]
              Snell, J., "Prefer Header for HTTP",
              draft-snell-http-prefer-18 (work in progress),
              January 2013.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP",
              RFC 5789, March 2010.

   [RFC6585]  Nottingham, M. and R. Fielding, "Additional HTTP Status
              Codes", RFC 6585, April 2012.

   [RFC6906]  Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
              March 2013.

   [apps-discuss]
              IETF, "IETF Apps-Discuss Mailing List", n.d.,
              <https://www.ietf.org/mailman/listinfo/apps-discuss>.




Nottingham              Expires December 12, 2013              [Page 10]

Internet-Draft               HTTP Link Hints                   June 2013


Appendix A.  Representing Link Hints in Link Headers

   A link hint can be represented in a Link header ([RFC5988], Section
   5) as a link-extension.

   When doing so, the JSON of the hint's content SHOULD be normalised to
   reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs
   (%x09), line feeds (%x0A) or carriage returns (%x0D).  When they are
   part of a string value, these characters MUST be escaped as described
   in [RFC4627] Section 2.5; otherwise, they MUST be discarded.

   Furthermore, if the content is an array or an object, the surrounding
   delimiters MUST be removed before serialisation.  In other words, the
   outermost object or array is represented without the braces ("{}") or
   brackets ("[]") respectively, but this does not apply to inner
   objects or arrays.

   For example, the two JSON values below are those of the fictitious
   "example" and "exmaple1" hints, respectively:

   "The Example Value"
   1.2

   In a Link header, they would be serialised as:

   Link: </>; rel="sample"; example="The Example Value";
         example1=1.2

   A more complex, single value for "example":

   [
     "foo",
     -1.23,
     true,
     ["charlie", "bennet"],
     {"cat": "thor"},
     false
   ]

   would be serialised as:

   Link: </>; rel="sample"; example="\"foo\", -1.23, true,
         [\"charlie\", \"bennet\"], {"cat": \"thor\"}, false"








Nottingham              Expires December 12, 2013              [Page 11]

Internet-Draft               HTTP Link Hints                   June 2013


Appendix B.  Acknowledgements

   Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne,
   Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their
   suggestions and feedback.


Appendix C.  Open Issues

   The following is a list of placeholders for open issues.

   o  Resource Hints
      *  indicate a POST to 201 Created pattern
      *  indicate an "action" POST
      *  outbound links
      *  forms?
   o  Representation Hints
      *  format profiles
      *  schema?
      *  deprecation


Author's Address

   Mark Nottingham

   Email: mnot@mnot.net
   URI:   http://www.mnot.net/























Nottingham              Expires December 12, 2013              [Page 12]


Html markup produced by rfcmarkup 1.107, available from http://tools.ietf.org/tools/rfcmarkup/