idnits 2.17.1 draft-gregorio-atompub-multipart-00.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 286. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 297. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 304. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 310. 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 (May 1, 2008) is 5811 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 May 1, 2008 5 Expires: November 2, 2008 7 AtomPub Multipart Media Creation 8 draft-gregorio-atompub-multipart-00 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 November 2, 2008. 35 Abstract 37 This specification defines how an Atom Publishing Protocol collection 38 should process multipart/related requests and also defines how a 39 service 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. Service Document Extension . . . . . . . . . . . . . . . . . . 4 55 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 57 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 58 8. Normative References . . . . . . . . . . . . . . . . . . . . . 7 59 Appendix A. Revision History . . . . . . . . . . . . . . . . . . . 8 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 Intellectual Property and Copyright Statements . . . . . . . . . . 9 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] represenatations 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 will be three round trips 83 in the typical Media Resource creation scenario; POST of the media, 84 GET of the Media Link Entry, and subsequent PUT of the updated Media 85 Link Entry. This specification reduces that to just a single round- 86 trip by allowing the client to package up the media and the 87 associated Media Link Entry into a single multipart/related 88 representation which is POSTed to the Media Collection. 90 The design of the handling of multipart/related representations was 91 aimed at backward compatibility, that is for non-multipart/related 92 aware clients to fully function. A second aim was to retain and 93 utilize the expressiveness of the current app:accept element in the 94 Service Document. The last aim was to ease the burden on clients by 95 allowing the mulitpart representation to be constructed in an order 96 that was convenient for the client. 98 1.3. Applicability 100 The applicability of multipart/related representations to AtomPub 101 Collections is restricted to just creating 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, and Service 110 Document are used as defined in [RFC5023]. 112 3. Multipart Representations 114 This section covers the constraints on a multipart/related 115 representation sent to a Media Collection. Section 4 covers how a 116 client discovers that a Media Collection accepts multipart/related 117 representations. 119 A multipart/related POST to a Media Collection MUST be a valid 120 multipart/related representation as defined by [RFC2387] and MUST 121 contain two body parts. One body part MUST be an Atom Entry with a 122 media type of 'application/atom+xml' or 'application/ 123 atom+xml;type=entry'. The other body part MUST be of a media type 124 acceptable to the collection. The order of the body parts and which 125 one is the 'root' object are not relavant and an AtomPub service MUST 126 accept otherwise valid multipart/related POST representations in 127 either order. 129 That is, if a client is creating a media resource of type image/png 130 it can either POST a multipart/related representation with a type 131 parameter of either "application/atom+xml;type=entry" or "image/png". 132 If the optional start parameter is provided it MAY point, via 133 Content-ID, to either the image/png or the application/atom+xml 134 object. 136 A successful POST of a multipart/related representation to a Media 137 Collection proceeds as any successful Media Resource creation. The 138 non-Atom object is used to create the Media Resource and the Atom 139 Entry object is used to create the Media Link Entry. Media Resource 140 creation proceeds as defined in Section 9.6 of [RFC5023] with a 141 successful creation returning a 201 status code and a Location: 142 header pointing to the newly created Media Link Entry. All other 143 aspects of [RFC5023] MUST be followed for Media Resource creation 144 including Slug: header processing. 146 4. Service Document Extension 148 An AtomPub service announces that it will accept multipart/related 149 POSTs by an extension to the app:accept element. The 'multipart' 150 attribute is boolean valued, either "yes" or "no", and a "yes" 151 indicates that the collection accepts multipart/related POSTs for the 152 value of the app:accept element. The following example indicates a 153 collection that allows the creation of resources with the Ogg 154 Bitstream Format and will also accept them in multipart form. 156 application/ogg 158 The 'multipart' attribute is foreign markup and will be ignored by 159 clients that do not understand multipart/related uploads. In 160 addition it permits the full range of the app:accept element to be 161 used. The following indicates that the collection accepts any image 162 media type and will also accept them in multipart form. 164 image/* 166 The 'multipart' attribute can only have values of "yes" or "no". If 167 not present the client MUST interpret the app:accept element as if 168 the multipart attribute were present and had the value "no". 170 The 'multipart' attribute allows clients that are unaware of 171 multipart/related to continue to operate as normal since the 172 multipart attribute is foreign markup. The alternative, which was to 173 put a multipart/related media type in the app:accept element loses 174 flexibility since the 'type' parameter to the multipart/related media 175 type accepts only media types and not media ranges. 177 5. Examples 179 Here is an example service document that contains two media 180 collections. The first collection accepts multipart/related POSTs 181 for video media types only. The second collection accepts multipart/ 182 related POSTs for image/jpeg and image/png media types. 184 185 187 188 Media Collections 189 191 Mostly Media 192 video/* 193 text/* 194 audio/* 195 196 198 Pictures Only 199 image/png 200 image/gif 201 202 203 205 Here is an example interaction of a client creating a new Media 206 Resource in the Pictures Only media collection using a png image in a 207 multipart/related representation. 209 POST /blog/pic HTTP/1.1 210 Host: example.org 211 Content-Length: nnnn 212 content-type: multipart/related; 213 boundary="===============1605871705==" 214 slug: The Beach 215 mime-version: 1.0 217 Media Post 218 --===============1605871705== 219 Content-Type: application/atom+xml; charset="utf-8" 220 MIME-Version: 1.0 222 223 224 The Beach 225 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 226 2005-10-07T17:17:08Z 227 Daffy 228 229 A nice sunset picture over the water. 230 231 232 --===============1605871705== 233 Content-Type: image/gif 234 MIME-Version: 1.0 236 GIF89a...binary image data... 237 --===============1605871705==-- 239 6. Security Considerations 241 The security considerations are the same as delineated in [RFC5023]. 243 7. IANA Considerations 245 No IANA actions are required by this document. 247 8. Normative References 249 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 250 Requirement Levels", BCP 14, RFC 2119, March 1997. 252 [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type", 253 RFC 2387, August 1998. 255 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 256 Protocol", RFC 5023, October 2007. 258 [1] 260 Appendix A. Revision History 262 00 - Initial Revision. 264 Author's Address 266 Joe Gregorio (editor) 267 Google 269 Email: joe@bitworking.org 270 URI: http://bitworking.org/ 272 Full Copyright Statement 274 Copyright (C) The IETF Trust (2008). 276 This document is subject to the rights, licenses and restrictions 277 contained in BCP 78, and except as set forth therein, the authors 278 retain all their rights. 280 This document and the information contained herein are provided on an 281 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 282 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 283 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 284 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 285 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 286 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 288 Intellectual Property 290 The IETF takes no position regarding the validity or scope of any 291 Intellectual Property Rights or other rights that might be claimed to 292 pertain to the implementation or use of the technology described in 293 this document or the extent to which any license under such rights 294 might or might not be available; nor does it represent that it has 295 made any independent effort to identify any such rights. Information 296 on the procedures with respect to rights in RFC documents can be 297 found in BCP 78 and BCP 79. 299 Copies of IPR disclosures made to the IETF Secretariat and any 300 assurances of licenses to be made available, or the result of an 301 attempt made to obtain a general license or permission for the use of 302 such proprietary rights by implementers or users of this 303 specification can be obtained from the IETF on-line IPR repository at 304 http://www.ietf.org/ipr. 306 The IETF invites any interested party to bring to its attention any 307 copyrights, patents or patent applications, or other proprietary 308 rights that may cover technology that may be required to implement 309 this standard. Please address the information to the IETF at 310 ietf-ipr@ietf.org.