1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
<pre>Independent Submission I. Dzmanashvili
Request for Comments: 6861 January 2013
Category: Informational
ISSN: 2070-1721
<span class="h1">The "create-form" and "edit-form" Link Relations</span>
Abstract
<a href="./rfc5988">RFC 5988</a> 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 <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="http://www.rfc-editor.org/info/rfc6861">http://www.rfc-editor.org/info/rfc6861</a>.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) 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.
<span class="grey">Dzmanashvili Informational [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc6861">RFC 6861</a> "create-form" and "edit-form" January 2013</span>
Table of Contents
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-2">2</a>
<a href="#section-2">2</a>. Notational Conventions ..........................................<a href="#page-2">2</a>
<a href="#section-3">3</a>. Link Relations ..................................................<a href="#page-3">3</a>
<a href="#section-3.1">3.1</a>. The "create-form" Link Relation Type .......................<a href="#page-3">3</a>
<a href="#section-3.1.1">3.1.1</a>. Using the "create-form" Link Relation ...............<a href="#page-3">3</a>
<a href="#section-3.2">3.2</a>. The "edit-form" Link Relation Type .........................<a href="#page-3">3</a>
<a href="#section-3.2.1">3.2.1</a>. Using the "edit-form" Link Relation .................<a href="#page-4">4</a>
<a href="#section-3.3">3.3</a>. Error-Handling Example .....................................<a href="#page-4">4</a>
<a href="#section-4">4</a>. IANA Considerations .............................................<a href="#page-4">4</a>
<a href="#section-4.1">4.1</a>. The Link Relation Registration "create-form" ...............<a href="#page-4">4</a>
<a href="#section-4.2">4.2</a>. The Link Relation Registration "edit-form" .................<a href="#page-5">5</a>
<a href="#section-5">5</a>. Security Considerations .........................................<a href="#page-5">5</a>
<a href="#section-6">6</a>. Internationalisation Considerations .............................<a href="#page-5">5</a>
<a href="#section-7">7</a>. Normative References ............................................<a href="#page-5">5</a>
<a href="#appendix-A">Appendix A</a>. Acknowledgements .......................................<a href="#page-6">6</a>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
<a href="./rfc5988">RFC 5988</a> [<a href="./rfc5988" title=""Web Linking"">RFC5988</a>] 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.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Notational Conventions</span>
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 [<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>].
<span class="grey">Dzmanashvili Informational [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc6861">RFC 6861</a> "create-form" and "edit-form" January 2013</span>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Link Relations</span>
The following link relations are defined.
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. The "create-form" Link Relation Type</span>
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"
<span class="h4"><a class="selflink" id="section-3.1.1" href="#section-3.1.1">3.1.1</a>. Using the "create-form" Link Relation</span>
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.
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. The "edit-form" Link Relation Type</span>
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>
<span class="grey">Dzmanashvili Informational [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc6861">RFC 6861</a> "create-form" and "edit-form" January 2013</span>
or, expressed as a Link header
Link: <...>; rel="edit-form"; title="Edit Entry"
<span class="h4"><a class="selflink" id="section-3.2.1" href="#section-3.2.1">3.2.1</a>. Using the "edit-form" Link Relation</span>
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.
<span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Error-Handling Example</span>
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>
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. IANA Considerations</span>
IANA has registered the "create-form" and "edit-form" link relations
below as per [<a href="./rfc5988" title=""Web Linking"">RFC5988</a>].
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. The Link Relation Registration "create-form"</span>
Relation Name:
create-form
Description:
The target IRI points to a resource where a submission form can be
obtained.
<span class="grey">Dzmanashvili Informational [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc6861">RFC 6861</a> "create-form" and "edit-form" January 2013</span>
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 <a href="#section-3">Section 3</a>.
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. The Link Relation Registration "edit-form"</span>
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 <a href="#section-3">Section 3</a>.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Security Considerations</span>
See <a href="./rfc5988#section-7">Section 7 of RFC 5988</a> [<a href="./rfc5988" title=""Web Linking"">RFC5988</a>].
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Internationalisation Considerations</span>
See <a href="./rfc5988#section-8">Section 8 of RFC 5988</a> [<a href="./rfc5988" title=""Web Linking"">RFC5988</a>].
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Normative References</span>
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
[<a id="ref-RFC5988">RFC5988</a>] Nottingham, M., "Web Linking", <a href="./rfc5988">RFC 5988</a>, October 2010.
<span class="grey">Dzmanashvili Informational [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc6861">RFC 6861</a> "create-form" and "edit-form" January 2013</span>
<span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Acknowledgements</span>
The author gratefully acknowledges the contributions of Jan
Algermissen.
Author's Address
Ioseb Dzmanashvili
EMail: ioseb.dzmanashvili@gmail.com
Dzmanashvili Informational [Page 6]
</pre>
|
