idnits 2.17.1 draft-gregorio-atompub-multipart-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 369. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 380. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 387. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 393. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 11, 2008) is 5677 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Gregorio, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track September 11, 2008 5 Expires: March 15, 2009 7 AtomPub Multipart Media Resource Creation 8 draft-gregorio-atompub-multipart-04 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on March 15, 2009. 35 Abstract 37 This specification defines how an Atom Publishing Protocol collection 38 may process multipart/related requests and also defines how a service 39 announces that it accepts multipart/related entities. 41 Editorial Note 43 To provide feedback on this Internet-Draft, join the Atom Protocol 44 mailing list (http://www.imc.org/atom-protocol/) [1]. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 50 1.2. Design Considerations . . . . . . . . . . . . . . . . . . 3 51 1.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Multipart Representations . . . . . . . . . . . . . . . . . . 4 54 4. Server Processing . . . . . . . . . . . . . . . . . . . . . . 4 55 5. Service Document Extension . . . . . . . . . . . . . . . . . . 5 56 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 58 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 59 9. Normative References . . . . . . . . . . . . . . . . . . . . . 10 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 Intellectual Property and Copyright Statements . . . . . . . . . . 11 63 1. Introduction 65 The Atom Publishing Protocol [RFC5023] defines Media Collections and 66 how to create a Media Resource by POSTing the media to the Media 67 Collection. RFC 5023 does not define handling multipart/related 68 [RFC2387] representations nor does it specify how the acceptance of 69 such representations should be advertised in the Service Document. 70 This specification covers both the processing and the Service 71 Document aspects of handling multipart/related content. 73 1.1. Notational Conventions 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in [RFC2119]. 79 1.2. Design Considerations 81 The primary objective of multipart/related POSTs is to reduce round- 82 trips for creating Media Resources. There are three round trips in 83 the typical Media Resource creation scenario; POST of the media, GET 84 of the Media Link Entry, and subsequent PUT of the updated Media Link 85 Entry. This specification reduces that to just a single round-trip 86 by allowing the client to package up the media and the associated 87 Media Link Entry into a single multipart/related representation which 88 is POSTed to the Media Collection. 90 The design of the handling of multipart/related representations is 91 aimed at backward compatibility, that is for non-multipart/related 92 aware clients to fully function. A second aim is to retain and 93 utilize the expressiveness of the current app:accept element in the 94 Service Document. The last aim is to ease the burden on clients by 95 allowing the multipart representation to be constructed in an order 96 that is convenient for the client. 98 1.3. Applicability 100 The applicability of multipart/related representations to AtomPub 101 Collections is restricted to the creation of new entries in Media 102 collections. It does not specify the creation or use of a resource 103 that supports a GET to return the multipart/related representation 104 nor does it specify the creation or use of a resource that supports a 105 PUT of a multipart/related representation. 107 2. Terminology 109 The terms Collection, Media Resource, Media Link Entry, Foreign 110 Markup, and Service Document are used as defined in [RFC5023]. The 111 term Object Root is used as defined in [RFC2387]. 113 3. Multipart Representations 115 This section covers the constraints on a multipart/related 116 representation sent to a Media Collection. Section 5 covers how a 117 client discovers that a Media Collection accepts multipart/related 118 representations. 120 There may be other specifications that define uses for multipart 121 representations in the AtomPub context; this specification only 122 describes one particular representation and how to use it in the 123 media-resource creation process. Follow-on multipart/related 124 specifications will have to define a method by which a server can 125 differentiate which specification is in force, which is beyond the 126 scope of this document. 128 A multipart/related POST to a Media Collection MUST be a valid 129 multipart/related representation as defined by [RFC2387] and MUST 130 contain two body parts. One, referred to as the Entry Part, MUST be 131 an Atom Entry with a media type of 'application/atom+xml' or 132 'application/atom+xml;type=entry'. The other, referred to as the 133 Media Part, MUST be of a media type acceptable to the collection. 134 The object root MUST be the Entry Part. The Entry Part's atom: 135 content element MUST have a 'src' attribute whose value is the URI of 136 the related media in the Media Part. The 'src' attribute value MUST 137 be a 'cid:' URI as defined by [RFC2392]. The Content-Type: header of 138 the POST request MUST specify "application/atom+xml;type=entry" or 139 "application/atom+xml". 141 4. Server Processing 143 A successful POST of a multipart/related representation to a Media 144 Collection causes several resource-creation processes to occur as 145 described in [RFC5023]. The Media Part is used to create a Media 146 Resource as if it had been posted as a request body to the collection 147 as described in section 9.6, and the Entry Part is used to create the 148 corresponding Media Link Entry. Assuming these two steps are 149 successful, the server returns a 201 status code and a Location: 150 header pointing to the newly created Media Link Entry. The 151 applicable rules from [RFC5023] MUST be followed, including Slug: 152 header processing. 154 While a multipart/related request replaces three round trips in the 155 typical Media Resource creation scenario, AtomPub has no mechanism to 156 report partial success. Thus, the handling of a multipart/related 157 request by the server MUST be atomic; that is, either succeed with a 158 201 Created status code, or return an error status code. 160 5. Service Document Extension 162 An AtomPub service announces that it will accept multipart/related 163 POSTs by an extension to the app:accept element. The "alternate" 164 attribute's value MUST be one or more tokens, space-separated if more 165 than one. The only token defined by this specification is 166 "multipart-related". The presence of the "multipart-related" token 167 in the 'alternate' attribute's value indicates that the collection 168 accepts multipart/related POSTs whose Media Part has a content-type 169 matching that specified in the app:accept element. The following 170 example indicates a collection that allows the creation of resources 171 with the Ogg Bitstream Format and will also accept them in multipart 172 form. 174 application/ogg 176 The 'alternate' attribute is foreign markup and will be ignored by 177 clients that do not understand multipart/related uploads. In 178 addition it permits the full range of the app:accept element to be 179 used. The following indicates that the collection accepts any image 180 media type and will also accept them in multipart form. 182 image/* 184 The 'alternate' attribute allows clients that are unaware of 185 multipart/related to continue to operate as normal since the 186 alternate attribute is foreign markup. The alternative, which is to 187 put a multipart/related media type in the app:accept element, loses 188 flexibility since the 'type' parameter to the multipart/related media 189 type accepts only media types and not media ranges. 191 6. Examples 193 Here is an example service document that contains two media 194 collections. The first collection accepts multipart/related POSTs 195 for video media types only. It does not accept multipart/related 196 POSTs for audio or text. The second collection accepts multipart/ 197 related POSTs for image/gif and image/png media types. 199 200 202 203 Media Collections 204 206 Mostly Media 207 video/* 208 text/* 209 audio/* 210 211 213 Pictures Only 214 image/png 215 image/gif 216 217 218 220 Here is an example interaction of a client creating a new Media 221 Resource in the Pictures Only media collection using a png image in a 222 multipart/related representation. 224 POST /blog/pic HTTP/1.1 225 Host: example.org 226 Content-Length: nnnn 227 Content-Type: multipart/related; 228 boundary="===============1605871705=="; 229 type="application/atom+xml" 230 Slug: The Beach 231 MIME-Version: 1.0 233 Media Post 234 --===============1605871705== 235 Content-Type: application/atom+xml; charset="utf-8" 236 MIME-Version: 1.0 238 239 240 The Beach 241 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 242 2005-10-07T17:17:08Z 243 Daffy 244 245 A nice sunset picture over the water. 246 247 249 250 --===============1605871705== 251 Content-Type: image/gif 252 MIME-Version: 1.0 253 Content-ID: <99334422@example.com> 255 GIF89a...binary image data... 256 --===============1605871705==-- 258 If the request was successful the response might look like: 260 HTTP/1.1 201 Created 261 Date: Fri, 7 Oct 2005 17:17:11 GMT 262 Content-Length: nnn 263 Content-Type: application/atom+xml;type=entry;charset="utf-8" 264 Location: http://example.org/media/edit/the_beach.atom 266 267 268 The Beach 269 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 270 2005-10-07T17:17:08Z 271 Daffy 272 273 A nice sunset picture over the water. 274 275 277 279 281 283 The initial request does not have to have the Entry Part first to 284 indicate that it is the object root, it's location can be indicated 285 by the 'start' attribute, as in this example. 287 POST /blog/pic HTTP/1.1 288 Host: example.org 289 Content-Length: nnnn 290 Content-Type: multipart/related; 291 boundary="===============1605871705=="; 292 type="application/atom+xml"; 293 start="<10101033@example.com>" 294 Slug: The Beach 295 MIME-Version: 1.0 297 Media Post 298 --===============1605871705== 299 Content-Type: image/gif 300 MIME-Version: 1.0 301 Content-ID: <99334422@example.com> 303 GIF89a...binary image data... 304 --===============1605871705== 305 Content-Type: application/atom+xml; charset="utf-8" 306 MIME-Version: 1.0 307 Content-ID: <10101033@example.com> 309 310 311 The Beach 312 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 313 2005-10-07T17:17:08Z 314 Daffy 315 316 A nice sunset picture over the water. 317 318 320 321 --===============1605871705==-- 323 7. Security Considerations 325 The security considerations are the same as delineated in [RFC5023]. 327 8. IANA Considerations 329 No IANA actions are required by this document. 331 9. Normative References 333 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 334 Requirement Levels", BCP 14, RFC 2119, March 1997. 336 [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type", 337 RFC 2387, August 1998. 339 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 340 Locators", RFC 2392, August 1998. 342 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 343 Protocol", RFC 5023, October 2007. 345 [1] 347 Author's Address 349 Joe Gregorio (editor) 350 Google 352 Email: joe@bitworking.org 353 URI: http://bitworking.org/ 355 Full Copyright Statement 357 Copyright (C) The IETF Trust (2008). 359 This document is subject to the rights, licenses and restrictions 360 contained in BCP 78, and except as set forth therein, the authors 361 retain all their rights. 363 This document and the information contained herein are provided on an 364 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 365 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 366 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 367 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 368 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 369 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 371 Intellectual Property 373 The IETF takes no position regarding the validity or scope of any 374 Intellectual Property Rights or other rights that might be claimed to 375 pertain to the implementation or use of the technology described in 376 this document or the extent to which any license under such rights 377 might or might not be available; nor does it represent that it has 378 made any independent effort to identify any such rights. Information 379 on the procedures with respect to rights in RFC documents can be 380 found in BCP 78 and BCP 79. 382 Copies of IPR disclosures made to the IETF Secretariat and any 383 assurances of licenses to be made available, or the result of an 384 attempt made to obtain a general license or permission for the use of 385 such proprietary rights by implementers or users of this 386 specification can be obtained from the IETF on-line IPR repository at 387 http://www.ietf.org/ipr. 389 The IETF invites any interested party to bring to its attention any 390 copyrights, patents or patent applications, or other proprietary 391 rights that may cover technology that may be required to implement 392 this standard. Please address the information to the IETF at 393 ietf-ipr@ietf.org.