idnits 2.17.1 draft-dusseault-http-patch-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors 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 (October 15, 2009) is 5279 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 (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Dusseault 3 Internet-Draft Linden Lab 4 Intended status: Standards Track J. Snell 5 Expires: April 18, 2010 October 15, 2009 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-15 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on April 18, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 Several applications extending the Hypertext Transfer Protocol (HTTP) 47 require a feature to do partial resource modification. The existing 48 HTTP PUT method only allows a complete replacement of a document. 50 This proposal adds a new HTTP method, PATCH, to modify an existing 51 HTTP resource. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. The PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. A simple PATCH example . . . . . . . . . . . . . . . . . . 5 58 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 59 3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6 60 3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 7 61 3.2. Example OPTIONS Request and Response . . . . . . . . . . . 7 62 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 7 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 67 6.2. Informative References . . . . . . . . . . . . . . . . . . 9 68 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 69 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9 70 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9 71 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9 72 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 9 73 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10 74 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10 75 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10 76 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 10 77 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 78 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11 79 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 12 80 B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 12 81 B.12. Changes from -11 . . . . . . . . . . . . . . . . . . . . . 12 82 B.13. Changes from -12 . . . . . . . . . . . . . . . . . . . . . 12 83 B.14. Changes from -13 . . . . . . . . . . . . . . . . . . . . . 12 84 B.15. Changes from -14 . . . . . . . . . . . . . . . . . . . . . 13 85 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 13 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 88 1. Introduction 90 This specification defines the new HTTP/1.1 [RFC2616] method PATCH 91 that is used to apply partial modifications to a resource. 93 A new method is necessary to improve interoperability and prevent 94 errors. The PUT method is already defined to overwrite a resource 95 with a complete new body, and can not be reused to do partial 96 changes. Otherwise, proxies and caches and even clients and servers 97 may get confused as to the result of the operation. PATCH was 98 mentioned in earlier HTTP specifications, but not completely defined. 100 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 101 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 102 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 104 Furthermore, this document uses the ABNF syntax defined in Section 105 2.1 of [RFC2616]. 107 2. The PATCH Method 109 The PATCH method requests that a set of changes described in the 110 request entity be applied to the resource identified by the Request- 111 URI. The set of changes is represented in a format called a "patch 112 document" identified by a media type. If the Request-URI does not 113 point to an existing resource, the server MAY create a new resource, 114 depending on the patch document type (whether it can logically modify 115 a null resource) and permissions etc. 117 PATCH is neither safe or idempotent as defined by [RFC2616], Section 118 9.1. 120 The difference between the PUT and PATCH requests is reflected in the 121 way the server processes the enclosed entity to modify the resource 122 identified by the Request-URI. In a PUT request, the enclosed entity 123 is considered to be a modified version of the resource stored on the 124 origin server and the client is requesting that the stored version be 125 replaced. With PATCH, however, the enclosed entity contains a set of 126 instructions describing how a resource currently residing on the 127 origin server should be modified to produce a new version. The PATCH 128 method affects the resource identified by the Request-URI, and also 129 MAY have side effects on other resources; i.e., new resources may be 130 created, or existing ones modified, by the application of a PATCH. 132 The server MUST apply the entire set of changes atomically and never 133 provide (e.g. in response to a GET during this operation) a 134 partially-modified representation. If the entire patch document 135 cannot be successfully applied then the server MUST fail the entire 136 request, applying none of the changes. The determination of what 137 constitutes a successful PATCH can vary depending on the patch 138 document and the type of resource being modified. See Error Handling 139 in Section 2.2 for details on status codes and possible error 140 conditions. 142 If the request passes through a cache and the Request-URI identifies 143 one or more currently cached entities, those entries SHOULD be 144 treated as stale. A response to this method is only cacheable if it 145 contains explicit freshness information (such as an Expires header or 146 "Cache-Control: max-age" directive) as well as the Content-Location 147 header matching the request-URI, indicating that the PATCH response 148 body is a resource representation. A cached PATCH response can only 149 be used to respond to subsequent GET and HEAD requests; it MUST NOT 150 be used to respond to other methods (in particular, PATCH). 152 Collisions from multiple PATCH requests are more dangerous than PUT 153 collisions, because a patch document that is not operating from a 154 known base point may corrupt the resource. Clients wishing to apply 155 a patch document to a known entity can first acquire the strong ETag 156 [RFC2616] of the resource to be modified, and use that Etag in the 157 If-Match header on the PATCH request to verify that the resource is 158 still unchanged. If a strong ETag is not available for a given 159 resource, the client can use If-Unmodified-Since as a less-reliable 160 safeguard. 162 Note that entity-headers contained in the request apply only to the 163 contained patch document and MUST NOT be applied to the resource 164 being modified. Thus, a Content-Language header could be present on 165 the request but it would only mean (for whatever that's worth) that 166 the patch document had a language. Servers SHOULD NOT store such 167 headers except as trace information, and SHOULD NOT use such header 168 values the same way they might be used on PUT requests. Therefore, 169 this document does not specify a way to modify a document's Content- 170 Type or Content-Language value through headers, though a mechanism 171 could well be designed to achieve this goal through a patch document. 173 There is no guarantee that a resource can be modified with PATCH. 174 Further, it is expected that different patch document formats will be 175 appropriate for different types of resources and that no single 176 format will be appropriate for all types of resources. Therefore, 177 there is no single default patch document format that implementations 178 are required to support. Servers MUST ensure that a received patch 179 document is appropriate for the type of resource identified by the 180 Request-URI. 182 Clients need to choose when to use PATCH rather than PUT. For 183 example, if the patch document size is larger than the size of the 184 new resource data that would be used in a PUT, then it might make 185 sense to use PUT instead of PATCH. A comparison to POST is even more 186 difficult, because POST is used in widely varying ways and can 187 encompass PUT and PATCH-like operations if the server chooses. If 188 the operation does not modify the resource identified by the Request- 189 URI in a predictable way, POST should be considered instead of PATCH 190 or PUT. 192 2.1. A simple PATCH example 194 PATCH /file.txt HTTP/1.1 195 Host: www.example.com 196 Content-Type: application/example 197 If-Match: "e0023aa4e" 198 Content-Length: 100 200 [description of changes] 202 This example illustrates use of a hypothetical patch document on an 203 existing resource. The 204 response code is used because the 204 response does not have a body (a response with the 200 code would 205 have a body) but other success codes MAY be used if appropriate. 207 Successful PATCH response to existing text file 209 HTTP/1.1 204 No Content 210 ETag: "e0023aa4f" 212 2.2. Error handling 214 There are several known conditions under which a PATCH request can 215 fail. 217 Malformed patch document: Can be specified using a 400 (Bad Request) 218 when the server finds that the patch document provided by the 219 client was not properly formatted. The definition of badly 220 formatted depends on the patch document chosen, but generally if 221 the server finds it cannot handle the patch due to the 222 serialization of the patch document, this response ought to be 223 appropriate. 224 Unsupported patch document: Can be specified using a 415 225 (Unsupported Media Type) when the client sends a patch document 226 format that the server does not support for the resource 227 identified by the Request-URI. Such a response SHOULD include an 228 Accept-Patch response header as described in Section 3.1 to notify 229 the client what patch document formats are supported. 231 Unprocessable request: Can be specified with a 422 (Unprocessable 232 Entity) ([RFC4918], Section 11.2) when the server understands the 233 patch document and the syntax of the patch document appears valid, 234 but the server is incapable of processing the request. This might 235 include attempts to modify a resource in a way that would cause 236 the resource to become invalid: for instance, a modification to a 237 well-formed XML document that would cause it to no longer be well- 238 formed. There may also be more specific errors like "Conflicting 239 State" that could be signaled with this status code, but the more 240 specific error would generally be more helpful. 241 Resource Not Found: Can be specified with a 404 (Not Found) status 242 code, when the client attempted to apply a patch document to a 243 non-existent resource, but the patch document chosen cannot be 244 applied to a non-existent resource. 245 Conflicting State: Can be specified with a 409 (Conflict) when the 246 request cannot be applied given the state of the resource. For 247 example, if the client attempted to apply a structural 248 modification and the structures assumed to exist did not exist 249 (with XML, a patch might specify changing element 'foo' to element 250 'bar' but element 'foo' might not exist). 251 Conflicting modification: Specified with a 412 (Precondition Failed) 252 when a client uses either the If-Match or If-Unmodified-Since 253 request headers and attempts to apply a patch document to a 254 resource whose state has changed since the patch was created. If 255 the server detects a possible conflicting modification and neither 256 the If-Match or If-Unmodified-Since request headers are used, the 257 server can return a 409 (Conflict) response. 258 Concurrent modification: When a server receives multiple concurrent 259 requests to modify a resource, those requests SHOULD be queued and 260 processed in the order in which they are received. If a server is 261 incapable of queuing concurrent requests, all subsequent requests 262 SHOULD be rejected with a 409 (Conflict) until the first 263 modification request is complete. 265 Other HTTP status codes can also be used under the appropriate 266 circumstances. 268 The entity body of error responses SHOULD contain enough information 269 to communicate the nature of the error to the client. The content- 270 type of the response entity can vary across implementations. 272 3. Advertising Support in OPTIONS 274 A server can advertise its support for the PATCH method by adding it 275 to the listing of allowed methods in the "Allow" OPTIONS response 276 header defined in HTTP/1.1. The PATCH method MAY appear in the 277 "Allow" header even if the Accept-Patch header is absent, in which 278 case the list of allowed patch documents is not advertised. 280 3.1. The Accept-Patch Header 282 This specification introduces a new response header "Accept-Patch" 283 used to specify the patch document formats accepted by the server. 284 "Accept-Patch" SHOULD appear in the OPTIONS response for any resource 285 that supports the use of the PATCH method. The presence of the 286 "Accept-Patch" header in response to any method is an implicit 287 indication that PATCH is allowed on the resource identified by the 288 Request-URI. The presence of a specific patch document format in 289 this header indicates that specific format is allowed on the resource 290 identified by the Request-URI. 292 Accept-Patch = "Accept-Patch" ":" 1#media-type 294 The Accept-Patch header specifies a comma separated listing of media- 295 types as defined by [RFC2616], Section 3.7. 297 3.2. Example OPTIONS Request and Response 299 [request] 301 OPTIONS /example/buddies.xml HTTP/1.1 302 Host: www.example.com 304 [response] 306 HTTP/1.1 200 OK 307 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 308 Accept-Patch: application/example, text/example 310 The examples show a server that supports PATCH generally using two 311 hypothetical patch document formats. 313 4. IANA Considerations 315 4.1. The 'Accept-Patch' Response Header 317 The 'Accept-Patch' response header should be added to the permanent 318 registry (see [RFC3864]). 320 Header field name: Accept-Patch 321 Applicable Protocol: HTTP 322 Author/Change controller: IETF 323 Specification document: this specification 325 5. Security Considerations 327 The security considerations for PATCH are nearly identical to the 328 security considerations for PUT ([RFC2616], Section 9.6). These 329 include authorizing requests (possibly through access control and/or 330 authentication) and ensuring that data is not corrupted through 331 transport errors or through accidental overwrites. Whatever 332 mechanisms are used for PUT can be used for PATCH as well. The 333 following considerations apply specially to PATCH. 335 A document that is patched might be more likely to be corrupted than 336 a document that is overridden in entirety, but that concern can be 337 addressed through the use of mechanisms such as conditional requests 338 using ETags and the If-Match request header. 340 Sometimes an HTTP intermediary might try to detect viruses being sent 341 via HTTP by checking the body of the PUT/POST request or GET 342 response. The PATCH method complicates such watch-keeping because 343 neither the source document nor the patch document might be a virus, 344 yet the result could be. This security consideration is not 345 materially different from those already introduced by byte-range 346 downloads, downloading patch documents, uploading zipped (compressed) 347 files and so on. 349 Individual patch documents will have their own specific security 350 considerations that will likely vary depending on the types of 351 resources being patched. The considerations for patched binary 352 resources, for instance, will be different than those for patched XML 353 documents. Servers MUST take adequate precautions to ensure that 354 malicious clients cannot consume excessive server resources (e.g., 355 CPU, disk I/O) through the client's use of PATCH. 357 6. References 359 6.1. Normative References 361 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 362 Requirement Levels", BCP 14, RFC 2119, March 1997. 364 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 365 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 366 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 368 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 369 Procedures for Message Header Fields", BCP 90, RFC 3864, 370 September 2004. 372 6.2. Informative References 374 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 375 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 377 Appendix A. Acknowledgements 379 PATCH is not a new concept, it first appeared in HTTP in drafts of 380 version 1.1 written by Roy Fielding and Henrik Frystyk and also 381 appears in Section 19.6.1.1 of RFC 2068. 383 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 384 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 385 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham, Michael 386 Balloni and Cyrus Daboo for review and advice on this document. 388 Appendix B. Changes 390 B.1. Changes from -00 392 OPTIONS support: removed "Patch" header definition and used Allow and 393 new "Accept-Patch" headers instead. 395 Supported delta encodings: removed vcdiff and diffe as these do not 396 have defined MIME types and did not seem to be strongly desired. 398 PATCH method definition: Clarified cache behavior. 400 B.2. Changes from -01 402 Removed references to XCAP - not yet a RFC. 404 Fixed use of MIME types (this "fix" now obsolete) 406 Explained how to use MOVE or COPY in conjunction with PATCH, to 407 create a new resource based on an existing resource in a different 408 location. 410 B.3. Changes from -02 412 Clarified that MOVE and COPY are really independent of PATCH. 414 Clarified when an ETag must change, and when Last-Modified must be 415 used. 417 Clarified what server should do if both Content-Type and IM headers 418 appear in PATCH request. 420 Filled in missing reference to DeltaV and ACL RFCs. 422 Stopped using 501 Unsupported for unsupported delta encodings. 424 Clarified what a static resource is. 426 Refixed use of MIME types for patch formats. 428 Limited the scope of some restrictions to apply only to usage of 429 required diff format. 431 B.4. Changes from -03 433 Various typographical, terminology consistency, and other minor 434 clarifications or fixes. 436 B.5. Changes from -04 438 Moved paragraphs on ACL and RFC3229 interoperability to new section. 440 Added security considerations. 442 Added IANA considerations, registration of new namespace, and 443 discontinued use of "DAV:" namespace for new elements. 445 Added example of error response. 447 B.6. Changes from -05 449 Due to various concerns it didn't seem likely the application/gdiff 450 registration could go through so switching to vcdiff as required diff 451 format, and to RFC3229's approach to specifying diff formats, 452 including use of the IM header. 454 Clarified what header server MUST use to return MD5 hash. 456 Reverted to using 501 Unsupported for unsupported delta encodings. 458 B.7. Changes from -06 460 The reliance on RFC 3229 defined patch documents has been factored 461 out in favor of delta encodings identified by MIME media type. 463 The required use of DeltaV-based error reporting has been removed in 464 favor of using basic HTTP status codes to report error conditions. 466 The Accept-Patch response header has been redefined as a listing of 467 media-ranges, similar to the Accept request header. 469 Added James Snell as a co-author. 471 B.8. Changes from -07 473 Terminology change from "delta encoding" to "patch document" 475 Added clarification on the safety and idempotency of PATCH 477 Updated the caching rules of PATCH responses 479 200 responses MUST include a representation of the modified resource. 480 204 responses are used to indicate successful response without 481 returning a representation. 483 Suggest using 422 Unprocessable Entity to indicate that a properly 484 formatted patch document cannot be processed 486 Clarify the use of 412 and 409 to indicate concurrent and conflicting 487 resource modifications. 489 Added registration for the Accept-Patch header. 491 Relaxed the requirements for the use of If-Match and If-Unmodified- 492 Since. 494 Add language that clarifies the difference between PUT and PATCH. 496 Add language that clarifies the issues with PATCH and Content 497 Negotiation. 499 Use of Accept-Patch on any response implies that PATCH is supported. 501 Add language advising caution when pipelining PATCH requests. 503 B.9. Changes from -08 505 Addition of the 209 Content Returned status code 507 Addition of the Prefer header field mechanism 509 Removed the paragraph discussing the use of 200+Content-Location. 510 This is replaced by the 209 Content Returned status code. 512 B.10. Changes from -09 514 Move the prefer header to a separate document 516 Restructure the document sections. 518 B.11. Changes from -10 520 Remove paragraph about pipelined requests. This is covered 521 adequately by RFC2616. 523 Remove paragraph about content negotiation. This is covered 524 adequately by RFC2616. 526 Explicitly indicate that PATCH can be used to create new resources. 528 Remove recommendation for servers to provide strong etags. This is 529 recommendation is implied and does not need to be explicitly. 531 Change Allow-Patch to a listing of media-type and not media-range. 533 B.12. Changes from -11 535 Fix section links. 537 State that this uses RFC2616-style ABNF. 539 Fix grammar for Accept-Patch. 541 Remove requirements for handling entity-headers on PATCH and replace 542 with general discussion of issues and consequences of having no 543 handling requirements. 545 Update Security Considerations to make it clear what security 546 considerations for PUT are, for comparison. 548 B.13. Changes from -12 550 Remove status 209 again. 552 Add security consideration about using too much server resources. 554 Remove Content-MD5 from example. 556 B.14. Changes from -13 558 Remove '*' value from Accept-Patch again. 560 Allow caching but only if context is clear. 562 Clarify how some patch formats might allow creating a new document. 564 Add comparison of PATCH to POST 566 B.15. Changes from -14 568 Clarified that Accept-Patch header SHOULD appear in OPTIONS response 569 -- it is not absolutely required 571 Clarified how server can indicate that a PATCH response body is 572 cachable as a resource representation. 574 Removed suggestion that PATCH side-effects might be specified in the 575 patch document specification -- this implied that side-effects could 576 exclusively be determined that way, but in fact side-effects are 577 often determined by the server unilaterally. 579 Appendix C. Notes to RFC Editor 581 The RFC Editor should remove this section and the Changes section. 583 Authors' Addresses 585 Lisa Dusseault 586 Linden Lab 587 945 Battery Street 588 San Francisco, CA 94111 589 USA 591 Email: lisa.dusseault@gmail.com 593 James M. Snell 595 Email: jasnell@gmail.com 596 URI: http://www.snellspace.com