Tech-invite  3GPPspace  IETFspace
96  95  94  93  92  91  90  89  88  87  86  85  84  83  82  81  80  79  78  77  76  75  74  73  72  71  70  69  68  67  66  65  64  63  62  61  60  59  58  57  56  55  54  53  52  51  50  49  48  47  46  45  44  43  42  41  40  39  38  37  36  35  34  33  32  31  30  29  28  27  26  25  24  23  22  21  20  19  18  17  16  15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00 
in Index   Prev   Next

RFC 6861

The "create-form" and "edit-form" Link Relations

Pages: 6
Informational

 Top   ToC   RFC6861 - Page 1 
Independent Submission                                   I. Dzmanashvili
Request for Comments: 6861                                  January 2013
Category: Informational
ISSN: 2070-1721


            The "create-form" and "edit-form" Link Relations


Abstract


   RFC 5988 standardized a means of indicating the relationships between
   resources on the Web.  This specification defines link relation types
   that may be used to express the relationships between a resource and
   an input form for constructing data submissions.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for informational purposes.

   This is a contribution to the RFC Series, independently of any other
   RFC stream.  The RFC Editor has chosen to publish this document at
   its discretion and makes no statement about its value for
   implementation or deployment.  Documents approved for publication by
   the RFC Editor are not a candidate for any level of Internet
   Standard; see Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6861.

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.
 Top   ToC   RFC6861 - Page 2 
Table of Contents


   1. Introduction ....................................................2
   2. Notational Conventions ..........................................2
   3. Link Relations ..................................................3
      3.1. The "create-form" Link Relation Type .......................3
           3.1.1. Using the "create-form" Link Relation ...............3
      3.2. The "edit-form" Link Relation Type .........................3
           3.2.1. Using the "edit-form" Link Relation .................4
      3.3. Error-Handling Example .....................................4
   4. IANA Considerations .............................................4
      4.1. The Link Relation Registration "create-form" ...............4
      4.2. The Link Relation Registration "edit-form" .................5
   5. Security Considerations .........................................5
   6. Internationalisation Considerations .............................5
   7. Normative References ............................................5
   Appendix A. Acknowledgements .......................................6


1.  Introduction


   RFC 5988 [RFC5988] standardized a means of indicating the
   relationships between resources on the Web.  This specification
   defines link relation types that may be used to express the
   relationships between a resource and an input form for constructing
   data submissions.

   The "create-form" and "edit-form" link relations are intentionally
   generic, and they can be used with multiple media types in a wide
   variety of use cases.


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].
 Top   ToC   RFC6861 - Page 3 
3.  Link Relations


   The following link relations are defined.


3.1.  The "create-form" Link Relation Type


   When included in a response, the "create-form" link relation
   indicates a target resource that represents a form that can be used
   to append a new member to the link context.

   <html>
     <ul>
       <li>Entry Description 1</li>
       <li>Entry Description 2</li>
     </ul>
     <a href="..." rel="create-form">[Add New Entry]</a>
   </html>

   or, expressed as a Link header

   Link: <...>; rel="create-form"; title="Add New Entry"


3.1.1.  Using the "create-form" Link Relation


   If the form representation includes a submission URI, this URI MUST
   be used to submit the form.  The context URI SHOULD be used
   otherwise.

   If the form representation includes a submission method, this method
   MUST be used for submit requests.  HTTP's POST method SHOULD be used
   otherwise.


3.2.  The "edit-form" Link Relation Type


   When included in a response, the "edit-form" link relation indicates
   a target resource that represents a form that can be used for
   updating the context resource.

   <html>
    ...
    <ul>
      <li>
        Entry Description 1
        <a href="..." rel="edit-form">[Edit Entry]</a>
      </li>
    </ul>
    ...
   </html>
 Top   ToC   RFC6861 - Page 4 
   or, expressed as a Link header

   Link: <...>; rel="edit-form"; title="Edit Entry"


3.2.1.  Using the "edit-form" Link Relation


   If the form representation includes a submission URI, this URI MUST
   be used to submit the form.  The context URI SHOULD be used
   otherwise.

   If the form representation includes a submission method, this method
   MUST be used for submit requests.  HTTP's PUT method SHOULD be used
   otherwise.


3.3.  Error-Handling Example


   When submitting forms in unsupported media type format, service may
   respond to the client with HTTP's 415 Unsupported Media Type status
   code.

     HTTP/1.1 415 Unsupported Media Type
     Link: <...>; rel="create-form"; title="Create new entry"
     Content-Type: text/html
     Content-Length: ...

     <html>
       Use <a href="..." rel="create-form">
         this form
       </a> to create a new entry.
     </html>


4.  IANA Considerations


   IANA has registered the "create-form" and "edit-form" link relations
   below as per [RFC5988].


4.1.  The Link Relation Registration "create-form"


   Relation Name:

      create-form

   Description:

      The target IRI points to a resource where a submission form can be
      obtained.
 Top   ToC   RFC6861 - Page 5 
   Security considerations:

      Automated agents should take care when this relation crosses
      administrative domains (e.g., the URI has a different authority
      than the current document).

   Reference:

      See Section 3.


4.2.  The Link Relation Registration "edit-form"


   Relation Name:

      edit-form

   Description:

      The target IRI points to a resource where a submission form for
      editing the associated resource can be obtained.

   Security Considerations:

      Automated agents should take care when this relation crosses
      administrative domains (e.g., the URI has a different authority
      than the current document).

   Reference:

      See Section 3.


5.  Security Considerations


   See Section 7 of RFC 5988 [RFC5988].


6.  Internationalisation Considerations


   See Section 8 of RFC 5988 [RFC5988].


7.  Normative References


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

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.
 Top   ToC   RFC6861 - Page 6 
Appendix A.  Acknowledgements


   The author gratefully acknowledges the contributions of Jan
   Algermissen.


Author's Address


   Ioseb Dzmanashvili

   EMail: ioseb.dzmanashvili@gmail.com