idnits 2.17.1 draft-gregorio-atompub-multipart-02.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 (July 15, 2008) is 5754 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 July 15, 2008 5 Expires: January 16, 2009 7 AtomPub Multipart Media Creation 8 draft-gregorio-atompub-multipart-02 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 January 16, 2009. 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. 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] 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 5 covers how a 116 client discovers that a Media Collection accepts multipart/related 117 representations. 119 This specification defines a format for multipart/related 120 representations sent to a Media Collection. There may be other 121 specifications that define formats for multipart representations, as 122 such this specification will only cover what constitutes a valid 123 representation for this specification. 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 body part MUST be an Atom Entry with a 131 media type of 'application/atom+xml' or 'application/ 132 atom+xml;type=entry'. The other body part MUST be of a media type 133 acceptable to the collection. The object root MUST be the Media Link 134 Entry. The Media Link Entry atom:content element MUST have a 'src' 135 attribute whose value is the URI of the related media contained in 136 the compound object. The 'src' attribute value MUST be a 'cid:' URI 137 as defined by [RFC2392]. The Content-Type: header of the POST 138 request MUST have a value of "application/atom+xml;type=entry" or 139 "application/atom+xml" for its required type parameter. 141 4. Server Processing 143 A successful POST of a multipart/related representation to a Media 144 Collection proceeds as any successful Media Resource creation. The 145 non-Atom object is used to create the Media Resource and the Atom 146 Entry object is used to create the Media Link Entry. Media Resource 147 creation proceeds as defined in Section 9.6 of [RFC5023] with a 148 successful creation returning a 201 status code and a Location: 149 header pointing to the newly created Media Link Entry. All other 150 aspects of [RFC5023] MUST be followed for Media Resource creation 151 including Slug: header processing. 153 While a multipart/related request replaces three round trips in the 154 typical Media Resource creation scenario, AtomPub has no mechanism to 155 report partial success and the handling of a multipart/related 156 request by the server MUST be atomic; it should either succeed with a 157 201 Created status code, or return an error status code. 159 5. Service Document Extension 161 An AtomPub service announces that it will accept multipart/related 162 POSTs by an extension to the app:accept element. The 'alternate' 163 attribute is a spaced separated list of tokens. The only token 164 defined by this specification is "multipart-related". The presence 165 of the "multipart-related" token in the 'alternate' attribute 166 indicates that the collection accepts multipart/related POSTs for the 167 value of the app:accept element. The following example indicates a 168 collection that allows the creation of resources with the Ogg 169 Bitstream Format and will also accept them in multipart form. 171 application/ogg 173 The 'multipart' attribute is foreign markup and will be ignored by 174 clients that do not understand multipart/related uploads. In 175 addition it permits the full range of the app:accept element to be 176 used. The following indicates that the collection accepts any image 177 media type and will also accept them in multipart form. 179 image/* 181 The default is collections do not accept multipart/related 182 representations. 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 was 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.