idnits 2.17.1 draft-dusseault-http-patch-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 78: '...te new body, and MUST NOT be reused to...' RFC 2119 keyword, line 111: '... the Request-URI MUST already exist (t...' RFC 2119 keyword, line 113: '...e's content type MUST be one to which ...' RFC 2119 keyword, line 114: '...ies. The server MUST apply the entire...' RFC 2119 keyword, line 117: '... MUST fail the entire request, apply...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 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 (April 2004) is 7314 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2518 (ref. '2') (Obsoleted by RFC 4918) ** Obsolete normative reference: RFC 2616 (ref. '3') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Possible downref: Non-RFC (?) normative reference: ref. '6' Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Individual Submission L. Dusseault 3 Internet-Draft OSAF 4 Expires: September 30, 2004 April 2004 6 Partial Document Changes (PATCH Method) for HTTP 7 draft-dusseault-http-patch-02 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt. 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 This Internet-Draft will expire on September 30, 2004. 32 Copyright Notice 34 Copyright (C) The Internet Society (2004). All Rights Reserved. 36 Abstract 38 Several applications extending HTTP require a feature to do partial 39 resource modification. Existing HTTP functionality only allows a 40 complete replacement of a document. This proposal adds a new HTTP 41 method, PATCH, to modify an existing HTTP resource. 43 1. Introduction 45 Three use cases initially motivated this proposal 47 1. WebDAV [2] is used by authoring applications to store and share 48 files on the internet. For example, Adobe Photoshop has a 49 Workgroup feature allowing the user to browse a repository and 50 save the file. Currently, Photoshop only publishes the file to 51 the repository rarely, because Photoshop files are typically 52 large and upload is slow. Worse, large uploads are more likely 53 to be interrupted. Although HTTP [3] provides byte range 54 downloads, it cannot provide this simple a mechanism for uploads. 55 2. DeltaV extends WebDAV to do versioning. In versioning 56 environments, a large number of files may be updated with very 57 small changes. For example, a programmer may change the name of 58 a function used in a hundred source files. Versioning 59 applications typically send deltas or 'diffs' to the server to 60 modify these files, however DetaV does not yet have this 61 functionality. 62 3. The SIMPLE WG is devising a way to store and modify configuration 63 information. The biggest feature missing from HTTP is the 64 ability to modify information in a very lightweight manner, so 65 that the client that decides to change its presence state from 66 "free" to "busy" doesn't have to upload a large document. This 67 can be accomplished through changes to a HTTP resource as well. 69 Other working groups (like netconf) are also considering manipulating 70 large files using HTTP GET and PUT. Sometimes the files aren't that 71 large but the device is small or bandwidth is limited, as when phones 72 need to add a new contact to an address book file. This feature 73 would allow much more efficient changes to files. 75 This specification defines a new HTTP 1.1 method for patches. A new 76 method is necessary to improve interoperability and prevent errors. 77 The PUT method is already defined to overwrite a resource with a 78 complete new body, and MUST NOT be reused to do partial changes. 79 Otherwise, proxies and caches and even clients and servers may get 80 confused as to the result of the operation. 82 Note that byte ranges are already used in HTTP to do partial 83 downloads (GET method). However, they are not defined for uploads, 84 and there are some missing pieces for uploads. For example, the HTTP 85 specification has no way for the server to send errors if the byte 86 range in a PUT is invalid. Byte ranges (or some other kind of range) 87 could be made to work in this specification but a more flexible 88 mechanism (one that could also encompass XML diffs) was desired, as 89 well as a method that would not confuse caching proxies. Reliable 90 and tested patch algorithms already exist as defined MIME [1] 91 document types, and this specification takes advantage of that 92 existing work. 94 Other delta encodings are defined for HTTP in RFC 3229 [4]. That 95 standard defines delta encodings for cache updates, not for user 96 write operations. It does mean that servers can reuse delta format 97 algorithms to support both that standard and this proposal. . 99 This standard defines the new method PATCH to alter a single existing 100 resource, in place, by applying a delta or diff file. The operation 101 is atomic. Note that WebDAV MOVE and COPY requests, if supported by 102 the HTTP server, can be useful to rename or copy a different resource 103 before applying PATCH. 105 2. Mechanisms 107 2.1 PATCH Method 109 The PATCH method requests that the request body (a patch document) be 110 applied to the resource named in the Request-URI. The resource named 111 in the Request-URI MUST already exist (the server MUST NOT create a 112 new resource with the body of the PATCH method). The target 113 resource's content type MUST be one to which the patch format 114 applies. The server MUST apply the entire patch atomically and never 115 provide (e.g. in response to a GET) a partially-patched body. If 116 the entire patch file cannot be successfully applied then the server 117 MUST fail the entire request, applying none of the changes. See 118 error handling section for details on status codes and possible error 119 conditions. 121 PATCH request bodies MUST NOT be cached. A cache MAY mark the 122 resource identified in the Request-URI as stale if it sees a 123 successful response to the PATCH request. 125 The PATCH request MUST have a body. It MUST include either the 126 Content-Type header with a MIME type value indicating what the body 127 type is, or an IM header as defined in RFC 3229 [4], to identify the 128 delta format. The IM header is only for gdiff and vcdiff, which are 129 instance manipulations, and the Content-Type header is for delta 130 formats which have registered MIME types. Either way, the identified 131 format MUST have the semantics of defining a change to an existing 132 document (such as gdiff). 134 The PATCH request is subject to access control, which in turn may 135 require authentication. The PATCH request SHOULD be subject to the 136 same access control permissions as the PUT request. 138 The PATCH request MUST only be used in a context which ensures that 139 only one user may apply a patch at a time. There are two reliable 140 ways to do this. The first way is to find out the resource ETag at 141 the time the body is downloaded, and use that Etag in the PATCH 142 request to make sure the resource is still unchanged. The second way 143 to use WebDAV LOCK/UNLOCK to reserve the file (first LOCK, then GET, 144 then PATCH, then UNLOCK). PATCH collisions from multiple users are 145 more dangerous than PUT collisions, because a PATCH that is not 146 operating from a known base point may corrupt the resource. 147 Therefore, if neither strong ETags nor LOCKS are available from the 148 server, the client MUST use If-Last-Modified as a less-reliable 149 safeguard. 151 Simple PATCH example 153 PATCH /file.txt HTTP/1.1 154 Host: www.example.com 155 IM: gdiff 156 If-Match: "e0023aa4e" 157 Content-Length: 100 159 0xd1, 0xff, 0xd1, 0xff 160 4 161 249,0,0,2 162 2,'X','Y 163 249,0,2,2 164 249,0,1,4 165 0 167 Figure 1 169 This example illustrates use of the platform-portable 'gdiff' 170 algorithm as one possible patch format. In this case the resource is 171 a text file. 173 2.2 PATCH Response 175 2.2.1 Success Response 177 The basic success response code for PATCH is 204 No Content. For 178 this new method, 200 OK is not used because 200 OK implies a body in 179 the response, and 201 Created is not used because the resource must 180 already exist. 182 The server SHOULD provide a MD5 hash of the content after the delta 183 was applied. This allows the client to verify the success of the 184 operation. The PATCH method obviously MUST cause the ETag to change. 185 So, if the server supports ETags, the server MUST return a strong 186 ETag for use in future client operations. If the server does not 187 support strong ETags, then the server MUST return the Last-Modified 188 header instead. 190 Successful PATCH response 192 HTTP/1.1 204 No Content 193 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 194 ETag: "e0023aa4e" 196 2.2.2 Error handling 198 This proposal uses the same mechanism as DeltaV to add much-needed 199 info to base HTTP error responses. Existing HTTP status codes are 200 not infinitely extensible but XML elements and namespaces are more 201 so, and it's simple to treat the HTTP error code as a rough category 202 and put detailed error codes in the body. 204 The PATCH method can return the following errors. Please note that 205 the notation "DAV:foobar" is merely short form for expressing "the 206 'foobar' element in the 'DAV:' namespace". It has meaning only in 207 English, not on the wire. Also note that the string error codes are 208 not meant to be displayed but instead as machine parsable known error 209 codes (thus there is no language code). 211 DAV:delta-format-unsupported: Used with 501 Not Supported status 212 code. Returned by the server when it doesn't support the delta 213 format chosen by the client. 215 DAV:delta-format-forbidden-on-resource: Used with 403 Forbidden when 216 the delta format chosen by the client is supported by the server 217 but not allowed on this kind of resource. 219 DAV:delta-format-badly-formatted: Used with 400 Bad Request when the 220 server finds that the delta document provided by the client was 221 badly formatted and non-compliant. 223 DAV:delta-empty-resource: Used with 409 Conflict when the resource 224 addressed in the Request-URI exists but is empty, and the delta 225 format cannot be applied to an empty document. Note that some 226 delta formats may be applied to an empty document, in which case 227 this error wouldn't be used. 229 DAV:patch-result-invalid: Used with 409 Conflict when the resource 230 could be patched but the result of the patch would be a resource 231 which is invalid. This could mean, for example, that a XML 232 resource would become an invalid XML file if the patch specified 233 that a close element text line should be deleted. 235 "404 Not Found" is used with no body/error element when the URL in by 236 the Request-URI does not map to a resource. 238 2.3 Delta Formats 240 A set of changes for a resource is itself a document, called a change 241 document or delta. The delta format is uniquely identified through a 242 MIME type. Servers advertise supported delta mechanisms by 243 advertising these MIME types, and clients specify which one they're 244 using by including the MIME type in the Content-Type header of the 245 PATCH request. 247 The VCDIFF [5] format identifier is "vcdiff". The GDIFF [6] format 248 identifier is "gdiff". Servers SHOULD support VCDIFF for all static 249 resources. 251 2.4 Advertising Support in OPTIONS 253 The server advertises its support for the features described here 254 with OPTIONS response headers. The "Allow" OPTIONS header is already 255 defined in HTTP 1.1 to contain all the allowable methods on the 256 addressed resource, so it's natural to add PATCH. 258 Clients also need to know whether the server supports special diff 259 formats, so this document introduces a new OPTIONS response header 260 "Accept-Patch". "Accept-Patch" MUST appear in the OPTIONS response 261 for any resource where the PATCH method is shown as an allowed 262 method. 264 OPTIONS * presents a bit of a special case, as it does not address a 265 resource, and does not always show all the server's features. In 266 responses to OPTIONS *, a server supporting this specification SHOULD 267 include the PATCH method in the "Allow" header and SHOULD show the 268 union of all supported diff methods in the "Accept-Patch" header. 270 Accept-Patch = "Accept-Patch" ":" #Delta-identifer 272 Delta-identifier = media-type | "gdiff" | "vcdiff" 274 Example: OPTIONS * request and response indicating Patch support 276 [request] 278 OPTIONS * HTTP/1.1 279 Host: www.example.com 281 [response] 283 HTTP/1.1 200 OK 284 Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH 285 Accept-Patch: gdiff, vcdiff, example/xcap+xml 287 Example: OPTIONS request and response for specific resource 289 [request] 291 OPTIONS /example/buddies.xml HTTP/1.1 292 Host: www.example.com 294 [response] 296 HTTP/1.1 200 OK 297 Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH 298 Accept-Patch: example/xcap+xml 300 3 References 302 [1] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 303 Extensions (MIME) Part Two: Media Types", RFC 2046, November 304 1996. 306 [2] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen, 307 "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, 308 February 1999. 310 [3] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 311 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 312 HTTP/1.1", RFC 2616, June 1999. 314 [4] Mogul, J., Krishnamurthy, B., Douglis, F., Feldmann, A., Goland, 315 Y., van Hoff, A. and D. Hellerstein, "Delta encoding in HTTP", 316 RFC 3229, January 2002. 318 [5] Korn, D., MacDonald, J., Mogul, J. and K. Vo, "The VCDIFF 319 Generic Differencing and Compression Data Format", RFC 3284, 320 June 2002. 322 [6] van Hoff, A. and J. Payne, "Generic Diff Format Specification", 323 August 1997. 325 Author's Address 327 Lisa Dusseault 328 Open Source Application Foundation 329 2064 Edgewood Dr. 330 Palo Alto, CA 94303 331 US 333 EMail: lisa@osafoundation.org 335 Appendix A. Acknowledgements 337 PATCH is not a new concept, it first appeared in HTTP in drafts of 338 version 1.1 written by Roy Fielding and Henrik Frystyk. 340 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 341 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther and 342 Alex Rousskov for review and advice on this document. 344 Appendix B. Changes 346 B.1 Changes from -00 348 OPTIONS support: removed "Patch" header definition and used Allow and 349 new "Accept-Patch" headers instead. 351 Supported delta formats: removed vcdiff and diffe as these do not 352 have defined MIME types and did not seem to be strongly desired. 354 PATCH method definition: Clarified cache behavior. 356 B.2 Changes from -01 358 Removed references to XCAP - not yet a standard. 360 Fixed use of MIME types since vcdiff and gdiff don't have registered 361 MIME types (similar usage to RFC3229), and added use of IM header for 362 same reason. 364 Explained how to use MOVE or COPY in conjunction with PATCH, to 365 create a new resource based on a delta of an existing resource in a 366 different location. 368 Intellectual Property Statement 370 The IETF takes no position regarding the validity or scope of any 371 intellectual property or other rights that might be claimed to 372 pertain to the implementation or use of the technology described in 373 this document or the extent to which any license under such rights 374 might or might not be available; neither does it represent that it 375 has made any effort to identify any such rights. Information on the 376 IETF's procedures with respect to rights in standards-track and 377 standards-related documentation can be found in BCP-11. Copies of 378 claims of rights made available for publication and any assurances of 379 licenses to be made available, or the result of an attempt made to 380 obtain a general license or permission for the use of such 381 proprietary rights by implementors or users of this specification can 382 be obtained from the IETF Secretariat. 384 The IETF invites any interested party to bring to its attention any 385 copyrights, patents or patent applications, or other proprietary 386 rights which may cover technology that may be required to practice 387 this standard. Please address the information to the IETF Executive 388 Director. 390 Full Copyright Statement 392 Copyright (C) The Internet Society (2004). All Rights Reserved. 394 This document and translations of it may be copied and furnished to 395 others, and derivative works that comment on or otherwise explain it 396 or assist in its implementation may be prepared, copied, published 397 and distributed, in whole or in part, without restriction of any 398 kind, provided that the above copyright notice and this paragraph are 399 included on all such copies and derivative works. However, this 400 document itself may not be modified in any way, such as by removing 401 the copyright notice or references to the Internet Society or other 402 Internet organizations, except as needed for the purpose of 403 developing Internet standards in which case the procedures for 404 copyrights defined in the Internet Standards process must be 405 followed, or as required to translate it into languages other than 406 English. 408 The limited permissions granted above are perpetual and will not be 409 revoked by the Internet Society or its successors or assignees. 411 This document and the information contained herein is provided on an 412 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 413 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 414 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 415 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 416 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 418 Acknowledgment 420 Funding for the RFC Editor function is currently provided by the 421 Internet Society.