idnits 2.17.1 draft-gregorio-atompub-multipart-03.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 328. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 339. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 346. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 352. 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 (August 15, 2008) is 5726 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 August 15, 2008 5 Expires: February 16, 2009 7 AtomPub Multipart Media Resource Creation 8 draft-gregorio-atompub-multipart-03 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 February 16, 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 . . . . . . . . . . . . . . . . . . . 8 58 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 59 9. Normative References . . . . . . . . . . . . . . . . . . . . . 8 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 Intellectual Property and Copyright Statements . . . . . . . . . . 10 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 Media 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 more more tokens, space-separated if 165 more 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 'multipart' 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. The second collection accepts multipart/ 196 related POSTs for image/jpeg and image/png media types. 198 199 201 202 Media Collections 203 205 Mostly Media 206 video/* 207 text/* 208 audio/* 209 210 212 Pictures Only 213 image/png 214 image/gif 215 216 217 219 Here is an example interaction of a client creating a new Media 220 Resource in the Pictures Only media collection using a png image in a 221 multipart/related representation. 223 POST /blog/pic HTTP/1.1 224 Host: example.org 225 Content-Length: nnnn 226 content-type: multipart/related; 227 boundary="===============1605871705==" 228 type="application/atom+xml" 229 slug: The Beach 230 mime-version: 1.0 232 Media Post 233 --===============1605871705== 234 Content-Type: application/atom+xml; charset="utf-8" 235 MIME-Version: 1.0 237 238 239 The Beach 240 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 241 2005-10-07T17:17:08Z 242 Daffy 243 244 A nice sunset picture over the water. 245 246 248 249 --===============1605871705== 250 Content-Type: image/gif 251 MIME-Version: 1.0 252 Content-ID: <99334422@example.com> 254 GIF89a...binary image data... 255 --===============1605871705==-- 257 If the request was successful the response might look like: 259 HTTP/1.1 201 Created 260 Date: Fri, 7 Oct 2005 17:17:11 GMT 261 Content-Length: nnn 262 Content-Type: application/atom+xml;type=entry;charset="utf-8" 263 Location: http://example.org/media/edit/the_beach.atom 265 266 267 The Beach 268 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 269 2005-10-07T17:17:08Z 270 Daffy 271 272 A nice sunset picture over the water. 273 274 276 278 280 282 7. Security Considerations 284 The security considerations are the same as delineated in [RFC5023]. 286 8. IANA Considerations 288 No IANA actions are required by this document. 290 9. Normative References 292 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 293 Requirement Levels", BCP 14, RFC 2119, March 1997. 295 [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type", 296 RFC 2387, August 1998. 298 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 299 Locators", RFC 2392, August 1998. 301 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 302 Protocol", RFC 5023, October 2007. 304 [1] 306 Author's Address 308 Joe Gregorio (editor) 309 Google 311 Email: joe@bitworking.org 312 URI: http://bitworking.org/ 314 Full Copyright Statement 316 Copyright (C) The IETF Trust (2008). 318 This document is subject to the rights, licenses and restrictions 319 contained in BCP 78, and except as set forth therein, the authors 320 retain all their rights. 322 This document and the information contained herein are provided on an 323 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 324 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 325 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 326 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 327 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 328 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 330 Intellectual Property 332 The IETF takes no position regarding the validity or scope of any 333 Intellectual Property Rights or other rights that might be claimed to 334 pertain to the implementation or use of the technology described in 335 this document or the extent to which any license under such rights 336 might or might not be available; nor does it represent that it has 337 made any independent effort to identify any such rights. Information 338 on the procedures with respect to rights in RFC documents can be 339 found in BCP 78 and BCP 79. 341 Copies of IPR disclosures made to the IETF Secretariat and any 342 assurances of licenses to be made available, or the result of an 343 attempt made to obtain a general license or permission for the use of 344 such proprietary rights by implementers or users of this 345 specification can be obtained from the IETF on-line IPR repository at 346 http://www.ietf.org/ipr. 348 The IETF invites any interested party to bring to its attention any 349 copyrights, patents or patent applications, or other proprietary 350 rights that may cover technology that may be required to implement 351 this standard. Please address the information to the IETF at 352 ietf-ipr@ietf.org.