idnits 2.17.1 draft-ioseb-dzmanashvili-link-relation-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC5988]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 16, 2012) is 4203 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Dzmanashvili 3 Internet-Draft October 16, 2012 4 Expires: April 19, 2013 6 The Create-Form and Edit-Form Link Relations 7 draft-ioseb-dzmanashvili-link-relation-08 9 Abstract 11 RFC 5988 [RFC5988] defined the way of indicating resources on the 12 Web. This specification defines link relation types which may be used 13 to express the relationships between a resource and an input form for 14 constructing data submissions. 16 Editorial Note (To be removed by RFC Editor) 18 Distribution of this document is unlimited. Comments should be sent 19 to the IETF Apps-Discuss mailing list (see 20 ). 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 19, 2013. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 58 3. Link Relations . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3.1. The "create-form" Link Relation Type . . . . . . . . . . . 3 60 3.1.1. Using the "create-form" Link Relation . . . . . . . . . 3 61 3.2. The "edit-form" Link Relation Type . . . . . . . . . . . . 4 62 3.2.1. Using the "edit-form" Link Relation . . . . . . . . . . 4 63 3.3. Error Handling Example . . . . . . . . . . . . . . . . . . 5 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 65 4.1. The Link Relation Registration "create-form" . . . . . . . 5 66 4.2. The Link Relation Registration "edit-form" . . . . . . . . 5 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 68 6. Internationalisation Considerations . . . . . . . . . . . . . . 6 69 7. Normative References . . . . . . . . . . . . . . . . . . . . . 6 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 72 1. Introduction 74 RFC 5988 [RFC5988] defined the way of indicating resources on the 75 Web. This specification defines link relation types which may be used 76 to express the relationships between a resource and an input form for 77 constructing data submissions. 79 The "create-form" and "edit-form" link relations are intentionally 80 generic, and they can be used with multiple media types in a wide 81 variety of use cases. 83 2. Notational Conventions 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in [RFC2119]. 89 3. Link Relations 91 The following link relations are defined. 93 3.1. The "create-form" Link Relation Type 95 When included in a response, the "create-form" link relation 96 indicates a target resource that represents a form that can be used 97 to append a new member to the link context. 99 100 104 [Add New Entry] 105 107 or, expressed as a Link header 109 Link: <...>; rel="create-form"; title="Add New Entry" 111 3.1.1. Using the "create-form" Link Relation 113 If the form representation includes a submission URI this URI MUST be 114 used to submit the form. The context URI SHOULD be used otherwise. 116 If the form representation includes a submission method this method 117 MUST be used for submit requests. HTTP's POST method SHOULD be used 118 otherwise. 120 3.2. The "edit-form" Link Relation Type 122 When included in a response, the "edit-form" link relation indicates 123 a target resource that represents a form that can be used for 124 updating the context resource. 126 127 ... 128 134 ... 135 137 or, expressed as a Link header 139 Link: <...>; rel="edit-form"; title="Edit Entry" 141 3.2.1. Using the "edit-form" Link Relation 143 If the form representation includes a submission URI this URI MUST be 144 used to submit the form. The context URI SHOULD be used otherwise. 146 If the form representation includes a submission method this method 147 MUST be used for submit requests. HTTP's PUT method SHOULD be used 148 otherwise. 150 3.3. Error Handling Example 152 When submitting forms in unsupported media type format, service may 153 respond to the client with HTTP's 415 Unsupported Media Type status 154 code. 156 HTTP/1.1 415 Unsupported Media Type 157 Link: <...>; rel="create-form"; title="Create new entry" 158 Content-Type: text/html 159 Content-Length: ... 161 162 Use 163 this form 164 to create a new entry. 165 167 4. IANA Considerations 169 IANA is asked to register the "create-form" and "edit-form" link 170 relations below as per [RFC5988]. 172 4.1. The Link Relation Registration "create-form" 174 Relation Name: 176 create-form 178 Description: 180 The target IRI points to a resource where a submission form can be 181 obtained. 183 Security considerations: 185 Automated agents should take care when this relation crosses 186 administrative domains (e.g., the URI has a different authority 187 than the current document). 189 Reference: 191 See Section 3. 193 4.2. The Link Relation Registration "edit-form" 195 Relation Name: 197 edit-form 199 Description: 201 The target IRI points to a resource where a submission form for 202 editing associated resource can be obtained. 204 Security Considerations: 206 Automated agents should take care when this relation crosses 207 administrative domains (e.g., the URI has a different authority 208 than the current document). 210 Reference: 212 See Section 3. 214 5. Security Considerations 216 See Section 7 of RFC5988 [RFC5988]. 218 6. Internationalisation Considerations 220 See Section 8 of RFC5988 [RFC5988]. 222 7. Normative References 224 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 225 Requirement Levels", BCP 14, RFC 2119, March 1997. 227 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 229 Appendix A. Acknowledgements 231 The author gratefully acknowledges the contributions of Jan 232 Algermissen. 234 Author's Address 236 Ioseb Dzmanashvili 238 EMail: ioseb.dzmanashvili@gmail.com