idnits 2.17.1 draft-dusseault-http-patch-07.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 475. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 486. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 493. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 499. 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 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: '... body, and MUST NOT be reused to do ...' RFC 2119 keyword, line 99: '...a media type and MUST include sufficie...' RFC 2119 keyword, line 102: '...ion. The server MUST NOT create a new...' RFC 2119 keyword, line 103: '...ody, although it MAY (depending on the...' RFC 2119 keyword, line 105: '... of the entity MUST NOT ignore any C...' (24 more instances...) 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 (June 22, 2007) is 6153 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) -- Looks like a reference, but probably isn't: 'RFC2518bis' on line 233 ** Obsolete normative reference: RFC 2616 (ref. '1') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 8 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: December 24, 2007 J. Snell 5 June 22, 2007 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-07 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 December 24, 2007. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007). 39 Abstract 41 Several applications extending HTTP require a feature to do partial 42 resource modification. Existing HTTP functionality only allows a 43 complete replacement of a document. This proposal adds a new HTTP 44 method, PATCH, to modify an existing HTTP resource. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 2.1. PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 4 51 2.2. PATCH Response . . . . . . . . . . . . . . . . . . . . . . 5 52 2.2.1. Success Response . . . . . . . . . . . . . . . . . . . 5 53 2.2.2. Error handling . . . . . . . . . . . . . . . . . . . . 5 54 2.3. Advertising Support in OPTIONS . . . . . . . . . . . . . . 7 55 3. Delta Encodings . . . . . . . . . . . . . . . . . . . . . . . 9 56 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 57 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 58 6. Normative References . . . . . . . . . . . . . . . . . . . . . 12 59 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 60 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 14 61 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 14 62 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 14 63 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 14 64 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 14 65 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 15 66 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 15 67 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 15 68 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 16 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 70 Intellectual Property and Copyright Statements . . . . . . . . . . 18 72 1. Introduction 74 This specification defines a new HTTP 1.1 [1] method PATCH that is 75 used to apply partial modifications to a HTTP resource. A new method 76 is necessary to improve interoperability and prevent errors. The PUT 77 method is already defined to overwrite a resource with a complete new 78 body, and MUST NOT be reused to do partial changes. Otherwise, 79 proxies and caches and even clients and servers may get confused as 80 to the result of the operation. 82 Note that byte ranges are already used in HTTP to do partial 83 downloads (GET method) as defined in RFC2616. However, they are not 84 defined for uploads, and there are some missing pieces for uploads. 85 For example, the HTTP specification does not define a particularly 86 informative error to send if the byte range in a PUT is invalid. 87 Byte ranges (or some other kind of range) could be made to work in 88 this specification but a more flexible mechanism (one that could also 89 encompass XML delta encodings) was desired, as well as a method that 90 would not confuse caching proxies. 92 2. Mechanisms 94 2.1. PATCH Method 96 The PATCH method requests that a set of changes described in the 97 request entity be applied to the resource identified by the Request- 98 URI. The set of changes is represented in a format called a "delta 99 encoding" identified by a media type and MUST include sufficient 100 information to allow the server to recreate the changes necessary to 101 convert the original version of the resource into the desired 102 version. The server MUST NOT create a new resource with the contents 103 of the request body, although it MAY (depending on the delta 104 encoding) apply the request body to an empty resource. The recipient 105 of the entity MUST NOT ignore any Content-* (e.g. Content-Range) 106 headers that it does not understand or implement and MUST return a 107 501 (Not Implemented) response in such cases. 109 The server SHOULD always apply the entire patch atomically and never 110 provide (e.g. in response to a GET during this operation) a 111 partially-patched body. If the entire delta encoding cannot be 112 successfully applied then the server MUST fail the entire request, 113 applying none of the changes. See error handling section for details 114 on status codes and possible error conditions. 116 The actual method for determining how to apply the delta encoding to 117 the resource is defined entirely by the origin server. 119 If the request passes through a cache and the Request-URI identifies 120 one or more currently cached entities, those entries SHOULD be 121 treated as stale. Responses to this method are not cacheable. 123 Collisions from multiple requests are more dangerous than PUT 124 collisions, because a delta encoding that is not operating from a 125 known base point may corrupt the resource. Therefore, the client 126 MUST verify that it is applying the delta encoding to a known entity 127 by first acquiring the strong ETag of the resource to be modified, 128 and using that Etag in the If-Match header on the PATCH request to 129 make sure the resource is still unchanged. If a strong ETag is not 130 available for a given resource, the client MUST use If-Unmodified- 131 Since as a less-reliable safeguard. 133 Servers SHOULD provide strong ETags for all resources for which the 134 PATCH method is supported. 136 Servers advertise the types of delta encoding documents supported for 137 PATCH, and clients specify which one they're using by including its 138 media type in the request using the Content-Type request header. 140 Simple PATCH example 142 PATCH /file.txt HTTP/1.1 143 Host: www.example.com 144 Content-type: application/delta 145 If-Match: "e0023aa4e" 146 Content-Length: 100 148 [description of changes] 150 Figure 1 152 This example illustrates use of a hypothetical delta encoding on an 153 existing text file. 155 2.2. PATCH Response 157 2.2.1. Success Response 159 A response with a 2xx status code indicates that the PATCH request 160 was a success. The server MAY include a representation of the 161 modified resource in the response and MAY include appropriate 162 Content-* headers to allow the client to verify the success of the 163 operation. 165 As with PUT, the PATCH method MUST change the resource's ETag if the 166 resulting entity is not identical to the original. If the server 167 supports strong ETags, the server MUST return a strong ETag for use 168 in future client operations. The server MUST return the Last- 169 Modified header if it does not support strong ETags. 171 Successful PATCH response to existing text file 173 HTTP/1.1 200 OK 174 ETag: "e0023aa4f" 175 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 176 Content-Type: text/plain 178 [modified resource] 180 2.2.2. Error handling 182 There are several known conditions under which a PATCH request can 183 fail. 185 Malformed Delta Encoding: Specified using a 400 Bad Request when the 186 server finds that the delta encoding provided by the client was 187 badly formatted or non-compliant. The definition of badly 188 formatted or non-compliant depends on the delta encoding chosen, 189 but generally if the server finds it can't handle the current 190 patch even though it supports the format used, this error ought to 191 be appropriate. 193 Unsupported Delta Encoding: Specified using a 415 Unsupported Media 194 Type when the client sends a delta encoding that the server 195 doesn't support for the resource identified by the Request-URI. 196 Such a response SHOULD include an Accept-Patch response header as 197 described in Section 2.3 to notify the client what delta encoding 198 formats are supported. 200 Patch Conflict: Specified with a 409 Conflict when the server 201 understands the delta encoding and the delta encoding looks valid, 202 but it cannot be applied to the resource. There are a number of 203 ways the resource could conflict with the delta encoding, for 204 example: 206 * The client attempted to apply a delta encoding to an empty 207 file, but the delta encoding chosen cannot be applied to an 208 empty file. 210 * The client attempted to apply a structural delta algorithm and 211 the structures assumed to exist didn't exist (e.g. an XML delta 212 which specifies changing element 'foo' to element 'bar' but 213 element 'foo' doesn't exist). 215 Concurrent modification: Specified with a 412 Precondition Failed 216 when a client attempts to apply a delta encoding to a resource 217 whose state has changed since the delta encoding was created. 219 Invalid Result: Specified with a 409 Conflict when the resource 220 could be patched but the result of the patch would be a resource 221 which is invalid. This could mean, for example, that a XML 222 resource would become an invalid XML file. 224 Other status codes MAY also be used under the appropriate 225 circumstances. For example, an unauthenticated user may be prompted 226 to authenticate, in order to use PATCH, with "401 Unauthorized". An 227 authenticated user who does not have sufficient privilege to use 228 PATCH may receive a "403 Forbidden" response. 230 The entity body of error responses SHOULD contain enough information 231 to communicate the nature of the error to the client. The content- 232 type of the response entity can vary across implementations. XML 233 error responses as defined by [RFC2518bis] MAY be used. 235 2.2.2.1. Example error response with body detail 237 HTTP/1.1 409 Conflict 238 Content-Type: text/plain; charset="utf-8" 239 Content-Length: xxx 241 Invalid result 243 2.3. Advertising Support in OPTIONS 245 The server advertises its support for the PATCH method with OPTIONS 246 response headers. The "Allow" OPTIONS header is already defined in 247 HTTP 1.1 to contain all the allowed methods on the addressed 248 resource, so the server MUST add PATCH if it is allowed. 250 Clients also need to know whether the server supports specific delta 251 encoding formats, so this document introduces a new response header 252 "Accept-Patch" used to specify the delta encoding formats accepted by 253 the server. "Accept-Patch" MUST appear in the OPTIONS response for 254 any resource where the PATCH method is shown as an allowed method. 256 OPTIONS * is not used to advertise support for PATCH because the 257 patch formats supported are likely to change from one resource to 258 another. A server MAY include the Accept-Patch header in response to 259 OPTIONS *, and its value MAY be the union of known supported delta 260 encodings for all types of resources. 262 Accept-Patch = "Accept-Patch" ":" #( media-range ) 264 The Accept-Patch header specifies a listing of media ranges as 265 defined by RFC2616 Section 14.1. Note that, unlike the HTTP Accept 266 request header, the Accept-Patch header does not use quality factors. 268 Example: OPTIONS request and response for specific resource 270 [request] 272 OPTIONS /example/buddies.xml HTTP/1.1 273 Host: www.example.com 275 [response] 277 HTTP/1.1 200 OK 278 Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH 279 Accept-Patch: application/diff, application/diff+xml 281 The examples show a server that supports PATCH generally using two 282 hypothetical delta encodings. 284 3. Delta Encodings 286 There is no guarantee that a resource can be modified with PATCH. 287 Further, it is expected that different delta encodings will be 288 appropriate for different types of resources and that no single delta 289 encoding will be appropriate for all types of resources. Therefore, 290 there is no single default delta encoding that implementations are 291 required to support. Servers MUST ensure that a received delta 292 encoding is appropriate for the type of resource identified by the 293 Request-URI. 295 Byte-based or binary delta encodings are useful for many types of 296 resources as long as the server stores resources identically to the 297 way they're presented on the wire (or can behave as if it does). 299 Character-based delta encodings operate on a variable number of bytes 300 depending on the length of each character, thus correct use of these 301 algorithms depends on the encoding of the resource. Such delta 302 encodings MUST either use the same character set encoding as the 303 resource being modified or MUST produce an otherwise valid result. 304 The validity of the result is dependent on the type of resource being 305 modified. 307 Structure-based delta encodings allow changes to be applied 308 independent of exact formats or canonicalizations. For example, a 309 delta encoding format targeted at the modification of XML-based 310 resources may allow for the insertion or deletion of elements and 311 attributes without concern for the exact serialization of those in 312 the modified resource. 314 4. IANA Considerations 316 This document does not specify any actions for IANA. 318 5. Security Considerations 320 The security considerations for PATCH are nearly identical to the 321 security considerations for PUT. In addition, one might be concerned 322 that a document that is patched might be more likely to be corrupted, 323 but that concern can be addressed through the use of mechanisms such 324 as conditional requests using ETags and the If-Match request header. 326 Sometimes an HTTP intermediary might try to detect viruses being sent 327 via HTTP by checking the body of the PUT/POST request or GET 328 response. The PATCH method complicates such watch-keeping because 329 neither the source document nor the patch document might be a virus, 330 yet the result could be. This security consideration is not 331 materially different from those already introduced by byte-range 332 downloads, downloading patch documents, uploading zipped (compressed) 333 files and so on. 335 Individual delta encodings will have their own specific security 336 considerations that will likely vary depending on the types of 337 resources being patched. The considerations for patched binary 338 resources, for instance, will be different than those for patched XML 339 documents. 341 6. Normative References 343 [1] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 344 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 345 HTTP/1.1", RFC 2616, June 1999. 347 Appendix A. Acknowledgements 349 PATCH is not a new concept, it first appeared in HTTP in drafts of 350 version 1.1 written by Roy Fielding and Henrik Frystyk. 352 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 353 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 354 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham and Michael 355 Balloni for review and advice on this document. 357 Appendix B. Changes 359 B.1. Changes from -00 361 OPTIONS support: removed "Patch" header definition and used Allow and 362 new "Accept-Patch" headers instead. 364 Supported delta encodings: removed vcdiff and diffe as these do not 365 have defined MIME types and did not seem to be strongly desired. 367 PATCH method definition: Clarified cache behavior. 369 B.2. Changes from -01 371 Removed references to XCAP - not yet a RFC. 373 Fixed use of MIME types (this "fix" now obsolete) 375 Explained how to use MOVE or COPY in conjunction with PATCH, to 376 create a new resource based on an existing resource in a different 377 location. 379 B.3. Changes from -02 381 Clarified that MOVE and COPY are really independent of PATCH. 383 Clarified when an ETag must change, and when Last-Modified must be 384 used. 386 Clarified what server should do if both Content-Type and IM headers 387 appear in PATCH request. 389 Filled in missing reference to DeltaV and ACL RFCs. 391 Stopped using 501 Unsupported for unsupported delta encodings. 393 Clarified what a static resource is. 395 Refixed use of MIME types for patch formats. 397 Limited the scope of some restrictions to apply only to usage of 398 required diff format. 400 B.4. Changes from -03 402 Various typographical, terminology consistency, and other minor 403 clarifications or fixes. 405 B.5. Changes from -04 407 Moved paragraphs on ACL and RFC3229 interoperability to new section. 409 Added security considerations. 411 Added IANA considerations, registration of new namespace, and 412 discontinued use of "DAV:" namespace for new elements. 414 Added example of error response. 416 B.6. Changes from -05 418 Due to various concerns it didn't seem likely the application/gdiff 419 registration could go through so switching to vcdiff as required diff 420 format, and to RFC3229's approach to specifying diff formats, 421 including use of the IM header. 423 Clarified what header server MUST use to return MD5 hash. 425 Reverted to using 501 Unsupported for unsupported delta encodings. 427 B.7. Changes from -06 429 The reliance on RFC 3229 defined delta encodings has been factored 430 out in favor of delta encodings identified by MIME media type. 432 The required use of DeltaV-based error reporting has been removed in 433 favor of using basic HTTP status codes to report error conditions. 435 The Accept-Patch response header has been redefined as a listing of 436 media-ranges with quality factors, similar to the Accept request 437 header. 439 Added James Snell as a co-author. 441 Appendix C. Notes to RFC Editor 443 The RFC Editor should remove this section and the Changes section. 445 Authors' Addresses 447 Lisa Dusseault 448 Open Source Application Foundation 449 2064 Edgewood Dr. 450 Palo Alto, CA 94303 451 US 453 Email: lisa@osafoundation.org 455 James M Snell 457 Phone: 458 Email: jasnell@gmail.com 459 URI: http://www.snellspace.com 461 Full Copyright Statement 463 Copyright (C) The IETF Trust (2007). 465 This document is subject to the rights, licenses and restrictions 466 contained in BCP 78, and except as set forth therein, the authors 467 retain all their rights. 469 This document and the information contained herein are provided on an 470 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 471 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 472 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 473 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 474 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 475 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 477 Intellectual Property 479 The IETF takes no position regarding the validity or scope of any 480 Intellectual Property Rights or other rights that might be claimed to 481 pertain to the implementation or use of the technology described in 482 this document or the extent to which any license under such rights 483 might or might not be available; nor does it represent that it has 484 made any independent effort to identify any such rights. Information 485 on the procedures with respect to rights in RFC documents can be 486 found in BCP 78 and BCP 79. 488 Copies of IPR disclosures made to the IETF Secretariat and any 489 assurances of licenses to be made available, or the result of an 490 attempt made to obtain a general license or permission for the use of 491 such proprietary rights by implementers or users of this 492 specification can be obtained from the IETF on-line IPR repository at 493 http://www.ietf.org/ipr. 495 The IETF invites any interested party to bring to its attention any 496 copyrights, patents or patent applications, or other proprietary 497 rights that may cover technology that may be required to implement 498 this standard. Please address the information to the IETF at 499 ietf-ipr@ietf.org. 501 Acknowledgment 503 Funding for the RFC Editor function is provided by the IETF 504 Administrative Support Activity (IASA).