idnits 2.17.1 draft-dusseault-http-patch-08.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 526. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 537. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 544. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 550. 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 2007) is 6160 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 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 7 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 3, 2007 J. Snell 5 June 2007 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-08 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 3, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2.1. PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3 51 2.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 5 52 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 53 2.3. Advertising Support in OPTIONS . . . . . . . . . . . . . . 7 54 2.3.1. Example . . . . . . . . . . . . . . . . . . . . . . . 7 55 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 56 3.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 8 57 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 58 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 59 5.1. Normative References . . . . . . . . . . . . . . . . . . . 9 60 5.2. Informative References . . . . . . . . . . . . . . . . . . 9 61 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 62 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9 63 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9 64 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9 65 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 10 66 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10 67 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10 68 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10 69 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 11 70 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 71 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 12 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 73 Intellectual Property and Copyright Statements . . . . . . . . . . 13 75 1. Introduction 77 This specification defines the new HTTP 1.1 [RFC2616] method PATCH 78 that is used to apply partial modifications to a HTTP resource. 80 A new method is necessary to improve interoperability and prevent 81 errors. The PUT method is already defined to overwrite a resource 82 with a complete new body, and can not be reused to do partial 83 changes. Otherwise, proxies and caches and even clients and servers 84 may get confused as to the result of the operation. 86 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 87 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 88 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 90 2. Mechanisms 92 2.1. PATCH Method 94 The PATCH method requests that a set of changes described in the 95 request entity be applied to the resource identified by the Request- 96 URI. The set of changes is represented in a format called a "patch 97 document" identified by a media type. PATCH is neither safe or 98 idempotent as defined by [RFC2616] Section 9.1. 100 The difference between the PUT and PATCH requests is reflected in the 101 way the server processes the enclosed entity to modify the resource 102 identified by the Request-URI. In a PUT request, the enclosed entity 103 is considered to be a modified version of the resource stored on the 104 origin server and the client is requesting that stored version be 105 replaced. With PATCH, however, the enclosed entity contains a set of 106 instructions describing how a resource currently residing on the 107 origin server should be modified to produce a new version. The 108 changes described by the entity MAY result in the creation of one or 109 more new resources on the server, however it is not intended that the 110 body of the PATCH request be used as the content of such resources. 112 The server MUST always apply the entire set of changes atomically and 113 never provide (e.g. in response to a GET during this operation) a 114 partially-modified representation. If the entire patch document 115 cannot be successfully applied then the server MUST fail the entire 116 request, applying none of the changes. The determination of what 117 constitutes a successful PATCH can vary depending on the patch 118 document and the type of resource being modified. The actual method 119 for determining how to apply the patch document to the resource is 120 defined entirely by the origin server. See Error Handling in section 121 2.2 for details on status codes and possible error conditions. 123 If the request passes through a cache and the Request-URI identifies 124 one or more currently cached entities, those entries SHOULD be 125 treated as stale. Responses to this method are not cacheable, unless 126 the response includes appropriate Cache-Control or Expires header 127 fields. However, the 303 (See Other) response can be used to direct 128 the user agent to retrieve a cacheable resource. 130 Collisions from multiple requests are more dangerous than PUT 131 collisions, because a patch document that is not operating from a 132 known base point may corrupt the resource. Clients wishing to apply 133 a patch document to a known entity can first acquire the strong ETag 134 of the resource to be modified, and use that Etag in the If-Match 135 header on the PATCH request to verify that the resource is still 136 unchanged. If a strong ETag is not available for a given resource, 137 the client can use If-Unmodified-Since as a less-reliable safeguard. 139 It is RECOMMENDED that Servers provide strong ETags for all resources 140 for which PATCH is supported. 142 A PATCH response with a 2xx status code indicates that the PATCH 143 request was a success. When the server responds with a status code 144 of 200 OK, it MUST include a representation of the modified resource. 145 A 200 response whose entity payload is empty indicates that the 146 result of the PATCH request is an empty resource. If the server 147 chooses not to return a representation of the modified resource, it 148 can use 204 No Content. With either a 200 or 204 response, the 149 server MAY include appropriate entity headers applied to the modified 150 resource to allow the client to verify the success of the operation. 152 The server MUST NOT ignore any Content-* (e.g. Content-Range) 153 headers that it does not understand or implement and MUST return a 154 501 (Not Implemented) response in such cases. 156 If the Request-URI identifies a resource with multiple alternate 157 representations, the server can choose to respond in a variety of 158 ways. For instance, the server can decide which representation to 159 alter and might even be able to change them all consistently 160 depending on the patch format. A particular patch document might be 161 able to identify specific representations to modify or might be 162 capable of describing changes to multiple representations. If the 163 server cannot choose a representation, it can reject the request with 164 an error or the server can choose to redirect the request (e.g. using 165 301 Moved Permanently or 302 Found), in which case the user agent 166 makes its own decision regarding whether or not to proceed with the 167 request. 169 Clients are advised to take caution when sending multiple PATCH 170 requests, or sequences of requests that include PATCH, over a 171 pipelined connection as there are no guarantees that pipelined 172 requests will be processed by the server in the same order in which 173 the client sends them. Such sequences of requests can be made safer 174 by using conditional request mechanisms such as If-Match. See 175 [RFC2616] Section 8.1.2.2 for additional details regarding pipelining 176 and non-idempotent requests. 178 There is no guarantee that a resource can be modified with PATCH. 179 Further, it is expected that different patch document formats will be 180 appropriate for different types of resources and that no single 181 format will be appropriate for all types of resources. Therefore, 182 there is no single default patch document format that implementations 183 are required to support. Servers MUST ensure that a received patch 184 document is appropriate for the type of resource identified by the 185 Request-URI. 187 2.1.1. Example 189 Simple PATCH example 191 PATCH /file.txt HTTP/1.1 192 Host: www.example.com 193 Content-type: application/example 194 If-Match: "e0023aa4e" 195 Content-Length: 100 197 [description of changes] 199 This example illustrates use of a hypothetical patch document on an 200 existing text file. 202 Successful PATCH response to existing text file 204 HTTP/1.1 200 OK 205 ETag: "e0023aa4f" 206 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 207 Content-Type: text/plain 209 [modified resource] 211 2.2. Error handling 213 There are several known conditions under which a PATCH request can 214 fail. 216 Malformed patch document: Can be specified using a 400 Bad Request 217 when the server finds that the patch document provided by the 218 client was improperly formatted. The definition of badly 219 formatted depends on the patch document chosen, but generally if 220 the server finds it cannot handle the patch due to the 221 serialization of the patch document, this response ought to be 222 appropriate. 223 Unsupported patch document: Specified using a 415 Unsupported Media 224 Type when the client sends a patch document that the server 225 doesn't support for the resource identified by the Request-URI. 226 Such a response SHOULD include an Accept-Patch response header as 227 described in Section 2.3 to notify the client what patch document 228 formats are supported. 229 Unprocessable request: Can be specified with a 422 Unprocessable 230 Entity [RFC4918] when the server understands the patch document 231 and the syntax of the patch document appears valid, but the server 232 is incapable of processing the request. There are a number of 233 situations that could lead to such a result, for example: 234 * The client attempted to apply a patch document to an empty 235 resource, but the patch document chosen cannot be applied to an 236 empty resource. 237 * The client attempted to apply a structural modification and the 238 structures assumed to exist did not exist (e.g. a patch which 239 specifies changing element 'foo' to element 'bar' but element 240 'foo' doesn't exist). 241 * The client attempted to modify a resource in a way that would 242 cause the resource to become invalid. For instance, a 243 modification to a well-formed XML document that would cause it 244 to no longer be well-formed. 245 * The client attempted to modify a resource that has multiple 246 representations but the server was unable to choose which 247 representation to modify. 248 Conflicting modification: Specified with a 412 Precondition Failed 249 when a client uses either the If-Match or If-Unmodified-Since 250 request headers and attempts to apply a patch document to a 251 resource whose state has changed since the patch was created. If 252 the server detects a possible conflicting modification and neither 253 the If-Match or If-Unmodified-Since request headers are used, the 254 server can return a 409 Conflict response. 255 Concurrent modification: When a server receives multiple concurrent 256 requests to modify a resource, those requests SHOULD be queued and 257 processed in the order in which they are received. If a server is 258 incapable of queuing concurrent requests, all subsequent requests 259 SHOULD be rejected using a 409 Conflict response until the first 260 modification request is complete. 262 Other HTTP status codes can also be used under the appropriate 263 circumstances. 265 The entity body of error responses SHOULD contain enough information 266 to communicate the nature of the error to the client. The content- 267 type of the response entity can vary across implementations. 269 2.3. Advertising Support in OPTIONS 271 A server can advertise its support for the PATCH method by adding it 272 to the listing of allowed methods in the "Allow" OPTIONS response 273 header defined in HTTP/1.1. 275 Clients also need to know whether the server supports specific patch 276 document formats, so this specification introduces a new response 277 header "Accept-Patch" used to specify the patch document formats 278 accepted by the server. "Accept-Patch" MUST appear in the OPTIONS 279 response for any resource that supports the use of the PATCH method. 280 The presence of the "Accept-Patch" header in response to any method 281 is an implicit indication that PATCH is allowed on the resource 282 identified by the Request-URI. 284 Accept-Patch = "Accept-Patch" ":" #( media-range ) 286 The Accept-Patch header specifies a listing of media ranges as 287 defined by [RFC2616], Section 14.1. Note that, unlike the HTTP 288 Accept request header, the Accept-Patch header does not use quality 289 factors. 291 2.3.1. Example 293 Example: OPTIONS request and response for specific resource 295 [request] 297 OPTIONS /example/buddies.xml HTTP/1.1 298 Host: www.example.com 300 [response] 302 HTTP/1.1 200 OK 303 Allow: GET, PUT, POST, OPTIONS, HEAD, TRACE, DELETE, PATCH 304 Accept-Patch: application/example, text/example 306 The examples show a server that supports PATCH generally using two 307 hypothetical patch documents. 309 3. IANA Considerations 311 3.1. The 'Accept-Patch' Response Header 313 The 'Accept-Patch' response header should be added to the permanent 314 registry (see [RFC3864]). 316 Header field name: Accept-Patch 318 Applicable Protocol: HTTP 320 Status: standard 322 Author/Change controller: IETF 324 Specification document: this specification 326 4. Security Considerations 328 The security considerations for PATCH are nearly identical to the 329 security considerations for PUT. In addition, one might be concerned 330 that a document that is patched might be more likely to be corrupted, 331 but that concern can be addressed through the use of mechanisms such 332 as conditional requests using ETags and the If-Match request header. 334 Sometimes an HTTP intermediary might try to detect viruses being sent 335 via HTTP by checking the body of the PUT/POST request or GET 336 response. The PATCH method complicates such watch-keeping because 337 neither the source document nor the patch document might be a virus, 338 yet the result could be. This security consideration is not 339 materially different from those already introduced by byte-range 340 downloads, downloading patch documents, uploading zipped (compressed) 341 files and so on. 343 Individual patch documents will have their own specific security 344 considerations that will likely vary depending on the types of 345 resources being patched. The considerations for patched binary 346 resources, for instance, will be different than those for patched XML 347 documents. 349 5. References 350 5.1. Normative References 352 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 353 Requirement Levels", BCP 14, RFC 2119, March 1997. 355 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 356 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 357 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 359 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 360 Procedures for Message Header Fields", BCP 90, RFC 3864, 361 September 2004. 363 5.2. Informative References 365 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 366 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 368 Appendix A. Acknowledgements 370 PATCH is not a new concept, it first appeared in HTTP in drafts of 371 version 1.1 written by Roy Fielding and Henrik Frystyk. 373 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 374 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 375 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham and Michael 376 Balloni for review and advice on this document. 378 Appendix B. Changes 380 B.1. Changes from -00 382 OPTIONS support: removed "Patch" header definition and used Allow and 383 new "Accept-Patch" headers instead. 385 Supported delta encodings: removed vcdiff and diffe as these do not 386 have defined MIME types and did not seem to be strongly desired. 388 PATCH method definition: Clarified cache behavior. 390 B.2. Changes from -01 392 Removed references to XCAP - not yet a RFC. 394 Fixed use of MIME types (this "fix" now obsolete) 395 Explained how to use MOVE or COPY in conjunction with PATCH, to 396 create a new resource based on an existing resource in a different 397 location. 399 B.3. Changes from -02 401 Clarified that MOVE and COPY are really independent of PATCH. 403 Clarified when an ETag must change, and when Last-Modified must be 404 used. 406 Clarified what server should do if both Content-Type and IM headers 407 appear in PATCH request. 409 Filled in missing reference to DeltaV and ACL RFCs. 411 Stopped using 501 Unsupported for unsupported delta encodings. 413 Clarified what a static resource is. 415 Refixed use of MIME types for patch formats. 417 Limited the scope of some restrictions to apply only to usage of 418 required diff format. 420 B.4. Changes from -03 422 Various typographical, terminology consistency, and other minor 423 clarifications or fixes. 425 B.5. Changes from -04 427 Moved paragraphs on ACL and RFC3229 interoperability to new section. 429 Added security considerations. 431 Added IANA considerations, registration of new namespace, and 432 discontinued use of "DAV:" namespace for new elements. 434 Added example of error response. 436 B.6. Changes from -05 438 Due to various concerns it didn't seem likely the application/gdiff 439 registration could go through so switching to vcdiff as required diff 440 format, and to RFC3229's approach to specifying diff formats, 441 including use of the IM header. 443 Clarified what header server MUST use to return MD5 hash. 445 Reverted to using 501 Unsupported for unsupported delta encodings. 447 B.7. Changes from -06 449 The reliance on RFC 3229 defined patch documents has been factored 450 out in favor of delta encodings identified by MIME media type. 452 The required use of DeltaV-based error reporting has been removed in 453 favor of using basic HTTP status codes to report error conditions. 455 The Accept-Patch response header has been redefined as a listing of 456 media-ranges, similar to the Accept request header. 458 Added James Snell as a co-author. 460 B.8. Changes from -07 462 Terminology change from "delta encoding" to "patch document" 464 Added clarification on the safety and idempotency of PATCH 466 Updated the caching rules of PATCH responses 468 200 responses MUST include a representation of the modified resource. 469 204 responses are used to indicate successful response without 470 returning a representation. 472 Suggest using 422 Unprocessable Entity to indicate that a properly 473 formatted patch document cannot be processed 475 Clarify the use of 412 and 409 to indicate concurrent and conflicting 476 resource modifications. 478 Added registration for the Accept-Patch header. 480 Relaxed the requirements for the use of If-Match and If-Unmodified- 481 Since. 483 Add language that clarifies the difference between PUT and PATCH. 485 Add language that clarifies the issues with PATCH and Content 486 Negotiation. 488 Use of Accept-Patch on any response implies that PATCH is supported. 490 Add language advising caution when pipelining PATCH requests. 492 Appendix C. Notes to RFC Editor 494 The RFC Editor should remove this section and the Changes section. 496 Authors' Addresses 498 Lisa Dusseault 499 Open Source Application Foundation 500 2064 Edgewood Dr. 501 Palo Alto, CA 94303 502 US 504 Email: lisa@osafoundation.org 506 James M Snell 508 Phone: 509 Email: jasnell@gmail.com 510 URI: http://www.snellspace.com 512 Full Copyright Statement 514 Copyright (C) The IETF Trust (2007). 516 This document is subject to the rights, licenses and restrictions 517 contained in BCP 78, and except as set forth therein, the authors 518 retain all their rights. 520 This document and the information contained herein are provided on an 521 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 522 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 523 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 524 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 525 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 526 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 528 Intellectual Property 530 The IETF takes no position regarding the validity or scope of any 531 Intellectual Property Rights or other rights that might be claimed to 532 pertain to the implementation or use of the technology described in 533 this document or the extent to which any license under such rights 534 might or might not be available; nor does it represent that it has 535 made any independent effort to identify any such rights. Information 536 on the procedures with respect to rights in RFC documents can be 537 found in BCP 78 and BCP 79. 539 Copies of IPR disclosures made to the IETF Secretariat and any 540 assurances of licenses to be made available, or the result of an 541 attempt made to obtain a general license or permission for the use of 542 such proprietary rights by implementers or users of this 543 specification can be obtained from the IETF on-line IPR repository at 544 http://www.ietf.org/ipr. 546 The IETF invites any interested party to bring to its attention any 547 copyrights, patents or patent applications, or other proprietary 548 rights that may cover technology that may be required to implement 549 this standard. Please address the information to the IETF at 550 ietf-ipr@ietf.org. 552 Acknowledgment 554 Funding for the RFC Editor function is provided by the IETF 555 Administrative Support Activity (IASA).