idnits 2.17.1 draft-dusseault-http-patch-03.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 abstract seems to contain references ([3]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** 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 117: '... [9] format identified as 'application/gdiff'. Servers SHOULD support...' RFC 2119 keyword, line 128: '...d in the Request-URI. The server MUST...' RFC 2119 keyword, line 130: '... although it MAY (depending on the p...' RFC 2119 keyword, line 132: '...ce's content type MUST be one to which...' (21 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 (July 15, 2004) is 7224 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) == Unused Reference: '7' is defined on line 339, but no explicit reference was found in the text ** 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) ** Obsolete normative reference: RFC 3230 (ref. '5') (Obsoleted by RFC 9530) -- Possible downref: Non-RFC (?) normative reference: ref. '9' Summary: 9 errors (**), 0 flaws (~~), 3 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: January 13, 2005 July 15, 2004 6 Partial Document Changes (PATCH Method) for HTTP 7 draft-dusseault-http-patch-03 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 http:// 25 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 January 13, 2005. 32 Copyright Notice 34 Copyright (C) The Internet Society (2004). All Rights Reserved. 36 Abstract 38 Several applications extending HTTP [3] require a feature to do 39 partial resource modification. Existing HTTP functionality only 40 allows a complete replacement of a document. This proposal adds a 41 new HTTP 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 provides byte range downloads, 54 it does not provide a mechanism for partial uploads. 55 2. DeltaV [6] 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, and this specification 91 takes advantage of that existing work. 93 Other delta encodings are defined for HTTP in RFC 3229 [4]. That 94 standard defines delta encodings for cache updates, not for user 95 write operations. It does mean that servers can reuse delta format 96 algorithms to support both that standard and this proposal. 98 This standard defines the new method PATCH to alter a single existing 99 resource, in place, by applying a delta or diff file. The operation 100 is atomic. Note that WebDAV MOVE and COPY requests, if supported by 101 the HTTP server, can be useful to independently rename or copy a 102 whole resource before applying PATCH to either the source or 103 destination URL to modify the contents. 105 2. Delta Formats 107 A set of changes for a resource is itself a document, called a patch 108 document or delta. The delta format is uniquely identified through a 109 MIME type. Servers advertise supported delta formats by advertising 110 these MIME types, and clients specify which one they're using by 111 including the MIME type in the request. MIME types were specifically 112 chosen so that there would be a well-defined way for other PATCH 113 extensions to define their own patch formats and how to use those 114 formats. 116 This specification only defines usage of the platform-portable gdiff 117 [9] format identified as 'application/gdiff'. Servers SHOULD support 118 gdiff for all authorable resources, that is all resources that 119 support PUT. Some requirements apply only to specific patch formats, 120 and in this specification those requirements are spelled out only for 121 gdiff. 123 3. Mechanisms 125 3.1 PATCH Method 127 The PATCH method requests that the request body (a patch document) be 128 applied to the resource named in the Request-URI. The server MUST 129 NOT create a new resource with the contents of the request body, 130 although it MAY (depending on the patch document format) apply the 131 request body to an empty entity to result in the content for the new 132 resource. The target resource's content type MUST be one to which 133 the patch format applies. The server MUST apply the entire patch 134 atomically and never provide (e.g. in response to a GET during this 135 operation) a partially-patched body. If the entire patch file cannot 136 be successfully applied then the server MUST fail the entire request, 137 applying none of the changes. See error handling section for details 138 on status codes and possible error conditions. 140 In the model defined in RFC3230 [5], the patch document is modelled 141 as an instance being sent to the server. Thus, if the server 142 supports instance manipulations, the client MAY apply these 143 manipulations to the patch document after it is generated (for 144 example, a compression algorithm). On the receiving end, the server 145 MUST undo the instance manipulation then apply the resulting document 146 as a delta. 148 PATCH request bodies MUST NOT be cached. A cache MAY mark the 149 resource identified in the Request-URI as stale if it sees a 150 successful response to the PATCH request. 152 The PATCH request MUST have a body. It MUST include the Content-Type 153 header with a MIME [1] type value identifying the delta format used 154 in the request body. The request body MUST be in some format which 155 has the semantics of defining a change to an existing document. 157 The PATCH request is subject to access control, which in turn may 158 require authentication. If the server supports the WebDAV Access 159 Control standard [8], then the PATCH request SHOULD be subject to the 160 same access control permissions as the PUT request. 162 If the gdiff format is used: 164 o The client MUST verify that it is applying the patch document to a 165 known entity. There are two reliable ways to do this. The first 166 way is to find out the resource ETag at the time the body is 167 downloaded, and use that Etag in the PATCH request to make sure 168 the resource is still unchanged. The second way to use WebDAV 169 LOCK/UNLOCK to reserve the file (first LOCK, then GET, then PATCH, 170 then UNLOCK). Gdiff collisions from multiple users are more 171 dangerous than PUT collisions, because a gdiff that is not 172 operating from a known base point may corrupt the resource. 173 Therefore, if neither strong ETags nor LOCKS are available from 174 the server, the client MUST use If-Last-Modified as a 175 less-reliable safeguard. 176 o If the Request-URI identifies an unmapped URL, the server SHOULD 177 (subject of course to access control and other restrictions) 178 create a resource with an empty body and apply the gdiff changes 179 to that empty entity. A client SHOULD verify that the URL is 180 unmapped, as expected, with use of the "If-None-Match: *" header. 182 Simple PATCH example 184 PATCH /file.txt HTTP/1.1 185 Host: www.example.com 186 Content-type: application/gdiff 187 If-Match: "e0023aa4e" 188 Content-Length: 100 190 0xd1, 0xff, 0xd1, 0xff 191 4 192 249,0,0,2 193 2,'X','Y 194 249,0,2,2 195 249,0,1,4 196 0 198 Figure 1 200 This example illustrates use of the gdiff algorithm on an existing 201 text file. 203 3.2 PATCH Response 205 3.2.1 Success Response 207 A successful response SHOULD have the 204 No Content status code or 208 the 201 Created status code if a new resource was created. Either 209 response indicates that the server successfully applied the delta and 210 that the response contains no body. 212 The server SHOULD provide a MD5 hash of the resource entity after the 213 delta was applied. This allows the client to verify the success of 214 the operation. The PATCH method MUST cause the ETag to change if the 215 resulting entity is not identical to the original. If the server 216 supports strong ETags, the server MUST return a strong ETag for use 217 in future client operations. The server SHOULD return the 218 Last-Modified header in any case, but the server MUST return the 219 Last-Modified header if ETags aren't supported. 221 Successful PATCH response to existing text file 223 HTTP/1.1 204 No Content 224 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 225 ETag: "e0023aa4e" 227 3.2.2 Error handling 229 This proposal uses the same mechanism as DeltaV to add much-needed 230 info to base HTTP error responses. Existing HTTP status codes are 231 not infinitely extensible but XML elements and namespaces are more 232 so, and it's simple to treat the HTTP error code as a rough category 233 and put detailed error codes in the body. Clients that do not use 234 the extra information ignore the bodies of error responses. 236 The PATCH method can return the following errors. Please note that 237 the notation "DAV:foobar" is merely short form for expressing "the 238 'foobar' element in the 'DAV:' namespace". It has meaning only in 239 this specification, not on the wire. Also note that the string error 240 codes are not meant to be displayed but instead as machine parsable 241 known error codes (thus there is no language code). 243 DAV:delta-format-unsupported: Used with 403 Forbidden status code. 244 Returned by the server when it doesn't support the delta format 245 chosen by the client. 247 DAV:delta-format-forbidden-on-resource: Used with 403 Forbidden when 248 the delta format chosen by the client is supported by the server 249 but not allowed on this kind of resource. 251 DAV:delta-format-badly-formatted: Used with 400 Bad Request when the 252 server finds that the delta document provided by the client was 253 badly formatted or non-compliant. The definition of badly 254 formatted or non-compliant depends on the delta format chosen, but 255 generally if the server finds it can't handle the diff entity even 256 though it supports the format used, this error ought to be 257 appropriate. 259 DAV:delta-empty-resource: Used with 409 Conflict when the resource 260 addressed in the Request-URI exists but is empty, and the delta 261 format cannot be applied to an empty document. Note that some 262 delta formats may be applied to an empty document, in which case 263 this error wouldn't be used. 265 DAV:patch-result-invalid: Used with 409 Conflict when the resource 266 could be patched but the result of the patch would be a resource 267 which is invalid. This could mean, for example, that a XML 268 resource would become an invalid XML file if the patch specified 269 that a close element text line should be deleted. 271 "404 Not Found" can be used (with no body/error element) when the URL 272 in by the Request-URI does not map to a resource and the server 273 cannot apply the patch document to a new empty resource (thus this 274 error wouldn't be used with gdiff patch documents). 276 3.3 Advertising Support in OPTIONS 278 The server advertises its support for the features described here 279 with OPTIONS response headers. The "Allow" OPTIONS header is already 280 defined in HTTP 1.1 to contain all the allowable methods on the 281 addressed resource, so it's natural to add PATCH. 283 Clients also need to know whether the server supports special diff 284 formats, so this document introduces a new OPTIONS response header 285 "Accept-Patch". "Accept-Patch" MUST appear in the OPTIONS response 286 for any resource where the PATCH method is shown as an allowed 287 method. 289 OPTIONS * is not used to advertise support for PATCH because the 290 delta formats supported are likely to change from one resource to 291 another. A server MAY include the Accept-Patch header in response to 292 OPTIONS *, and its value MAY be the union of known supported delta 293 formats. 295 Accept-Patch = "Accept-Patch" ":" #media-type 296 Example: OPTIONS request and response for specific resource 298 [request] 300 OPTIONS /example/buddies.xml HTTP/1.1 301 Host: www.example.com 303 [response] 305 HTTP/1.1 200 OK 306 Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH 307 Accept-Patch: example/xcap+xml, application/gdiff 309 The examples show a server that supports PATCH generally, with two 310 formats supported (one of them is fictional). On some resources, for 311 example on XML files, different kinds of diff formats more 312 appropriate to the resource may be supported. 314 4 References 316 [1] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 317 Extensions (MIME) Part Two: Media Types", RFC 2046, November 318 1996. 320 [2] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen, 321 "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, 322 February 1999. 324 [3] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 325 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 326 HTTP/1.1", RFC 2616, June 1999. 328 [4] Mogul, J., Krishnamurthy, B., Douglis, F., Feldmann, A., Goland, 329 Y., van Hoff, A. and D. Hellerstein, "Delta encoding in HTTP", 330 RFC 3229, January 2002. 332 [5] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", RFC 3230, 333 January 2002. 335 [6] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and J. Whitehead, 336 "Versioning Extensions to WebDAV (Web Distributed Authoring and 337 Versioning)", RFC 3253, March 2002. 339 [7] Korn, D., MacDonald, J., Mogul, J. and K. Vo, "The VCDIFF 340 Generic Differencing and Compression Data Format", RFC 3284, 341 June 2002. 343 [8] Clemm, G., Reschke, J., Sedlar, E. and J. Whitehead, "Web 344 Distributed Authoring and Versioning (WebDAV) Access Control 345 Protocol", RFC 3744, May 2004. 347 [9] van Hoff, A. and J. Payne, "Generic Diff Format Specification", 348 W3C NOTE-gdiff-19970901, August 1997. 350 Author's Address 352 Lisa Dusseault 353 Open Source Application Foundation 354 2064 Edgewood Dr. 355 Palo Alto, CA 94303 356 US 358 EMail: lisa@osafoundation.org 360 Appendix A. Acknowledgements 362 PATCH is not a new concept, it first appeared in HTTP in drafts of 363 version 1.1 written by Roy Fielding and Henrik Frystyk. 365 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 366 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 367 Rousskov and Jamie Lokier for review and advice on this document. 369 Appendix B. Changes 371 B.1 Changes from -00 373 OPTIONS support: removed "Patch" header definition and used Allow and 374 new "Accept-Patch" headers instead. 376 Supported delta formats: removed vcdiff and diffe as these do not 377 have defined MIME types and did not seem to be strongly desired. 379 PATCH method definition: Clarified cache behavior. 381 B.2 Changes from -01 383 Removed references to XCAP - not yet a standard. 385 Fixed use of MIME types (this "fix" now obsolete) 387 Explained how to use MOVE or COPY in conjunction with PATCH, to 388 create a new resource based on a delta of an existing resource in a 389 different location. 391 B.3 Changes from -02 393 Clarified that MOVE and COPY are really independent of PATCH. 395 Clarified when an ETag must change, and when Last-Modified must be 396 used. 398 Clarified what server should do if both Content-Type and IM headers 399 appear in PATCH request. 401 Filled in missing reference to DeltaV and ACL RFCs. 403 Stopped using 501 Unsupported for unsupported delta formats. 405 Clarified what a static resource is. 407 Refixed use of MIME types for delta formats. 409 Limited the scope of some restrictions to apply only to 'gdiff' 410 usage. 412 Intellectual Property Statement 414 The IETF takes no position regarding the validity or scope of any 415 intellectual property or other rights that might be claimed to 416 pertain to the implementation or use of the technology described in 417 this document or the extent to which any license under such rights 418 might or might not be available; neither does it represent that it 419 has made any effort to identify any such rights. Information on the 420 IETF's procedures with respect to rights in standards-track and 421 standards-related documentation can be found in BCP-11. Copies of 422 claims of rights made available for publication and any assurances of 423 licenses to be made available, or the result of an attempt made to 424 obtain a general license or permission for the use of such 425 proprietary rights by implementors or users of this specification can 426 be obtained from the IETF Secretariat. 428 The IETF invites any interested party to bring to its attention any 429 copyrights, patents or patent applications, or other proprietary 430 rights which may cover technology that may be required to practice 431 this standard. Please address the information to the IETF Executive 432 Director. 434 Full Copyright Statement 436 Copyright (C) The Internet Society (2004). All Rights Reserved. 438 This document and translations of it may be copied and furnished to 439 others, and derivative works that comment on or otherwise explain it 440 or assist in its implementation may be prepared, copied, published 441 and distributed, in whole or in part, without restriction of any 442 kind, provided that the above copyright notice and this paragraph are 443 included on all such copies and derivative works. However, this 444 document itself may not be modified in any way, such as by removing 445 the copyright notice or references to the Internet Society or other 446 Internet organizations, except as needed for the purpose of 447 developing Internet standards in which case the procedures for 448 copyrights defined in the Internet Standards process must be 449 followed, or as required to translate it into languages other than 450 English. 452 The limited permissions granted above are perpetual and will not be 453 revoked by the Internet Society or its successors or assignees. 455 This document and the information contained herein is provided on an 456 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 457 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 458 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 459 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 460 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 462 Acknowledgment 464 Funding for the RFC Editor function is currently provided by the 465 Internet Society.