idnits 2.17.1 draft-dusseault-http-patch-14.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 (April 13, 2009) is 5492 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 Messaging Architects 4 Intended status: Standards Track J. Snell 5 Expires: October 15, 2009 April 13, 2009 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-14 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 October 15, 2009. 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 . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . 7 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 67 6.2. Informative References . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . . . . 11 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 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 13 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 87 1. Introduction 89 This specification defines the new HTTP/1.1 [RFC2616] method PATCH 90 that is used to apply partial modifications to a resource. 92 A new method is necessary to improve interoperability and prevent 93 errors. The PUT method is already defined to overwrite a resource 94 with a complete new body, and can not be reused to do partial 95 changes. Otherwise, proxies and caches and even clients and servers 96 may get confused as to the result of the operation. 98 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 99 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 100 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 102 Furthermore, this document uses the ABNF syntax defined in Section 103 2.1 of [RFC2616]. 105 2. The PATCH Method 107 The PATCH method requests that a set of changes described in the 108 request entity be applied to the resource identified by the Request- 109 URI. The set of changes is represented in a format called a "patch 110 document" identified by a media type. If the Request-URI does not 111 point to an existing resource, the server MAY create a new resource, 112 depending on the patch document type (whether it can logically modify 113 a null resource) and permissions etc. 115 PATCH is neither safe or idempotent as defined by [RFC2616], Section 116 9.1. 118 The difference between the PUT and PATCH requests is reflected in the 119 way the server processes the enclosed entity to modify the resource 120 identified by the Request-URI. In a PUT request, the enclosed entity 121 is considered to be a modified version of the resource stored on the 122 origin server and the client is requesting that the stored version be 123 replaced. With PATCH, however, the enclosed entity contains a set of 124 instructions describing how a resource currently residing on the 125 origin server should be modified to produce a new version. The PATCH 126 method affects the resource identified by the Request-URI, and also 127 MAY have side effects on other resources; i.e., new resources may be 128 created, or existing ones modified, by the application of a PATCH 129 (again, depending on the patch document type). 131 The server MUST apply the entire set of changes atomically and never 132 provide (e.g. in response to a GET during this operation) a 133 partially-modified representation. If the entire patch document 134 cannot be successfully applied then the server MUST fail the entire 135 request, applying none of the changes. The determination of what 136 constitutes a successful PATCH can vary depending on the patch 137 document and the type of resource being modified. See Error Handling 138 in Section 2.2 for details on status codes and possible error 139 conditions. 141 If the request passes through a cache and the Request-URI identifies 142 one or more currently cached entities, those entries SHOULD be 143 treated as stale. Responses to this method are only cacheable if the 144 server indicates, and if the cacheable resource is indicated with the 145 Content-Location header. 147 Collisions from multiple PATCH requests are more dangerous than PUT 148 collisions, because a patch document that is not operating from a 149 known base point may corrupt the resource. Clients wishing to apply 150 a patch document to a known entity can first acquire the strong ETag 151 of the resource to be modified, and use that Etag in the If-Match 152 header on the PATCH request to verify that the resource is still 153 unchanged. If a strong ETag is not available for a given resource, 154 the client can use If-Unmodified-Since as a less-reliable safeguard. 156 Note that entity-headers contained in the request apply only to the 157 contained patch document and MUST NOT be applied to the resource 158 being modified. Thus, a Content-Language header could be present on 159 the request but it would only mean (for whatever that's worth) that 160 the patch document had a language. Servers SHOULD NOT store such 161 headers except as trace information, and SHOULD NOT use such header 162 values the same way they might be used on PUT requests. Therefore, 163 this document does not specify a way to modify a document's Content- 164 Type or Content-Language value through headers, though a mechanism 165 could well be designed to achieve this goal through a patch document. 167 There is no guarantee that a resource can be modified with PATCH. 168 Further, it is expected that different patch document formats will be 169 appropriate for different types of resources and that no single 170 format will be appropriate for all types of resources. Therefore, 171 there is no single default patch document format that implementations 172 are required to support. Servers MUST ensure that a received patch 173 document is appropriate for the type of resource identified by the 174 Request-URI. 176 Clients need to choose when to use PATCH rather than PUT. For 177 example, if the patch document size is larger than the size of the 178 new resource data that would be used in a PUT, then it might make 179 sense to use PUT instead of PATCH. A comparison to POST is even more 180 difficult, because POST is used in widely varying ways and can 181 encompass PUT and PATCH-like operations if the server chooses. If 182 the operation does not modify the resource identified by the Request- 183 URI in a predictable way, POST should be considered instead of PATCH 184 or PUT. 186 2.1. A simple PATCH example 188 PATCH /file.txt HTTP/1.1 189 Host: www.example.com 190 Content-Type: application/example 191 If-Match: "e0023aa4e" 192 Content-Length: 100 194 [description of changes] 196 This example illustrates use of a hypothetical patch document on an 197 existing resource. 199 Successful PATCH response to existing text file 201 HTTP/1.1 204 No Content 202 ETag: "e0023aa4f" 204 2.2. Error handling 206 There are several known conditions under which a PATCH request can 207 fail. 209 Malformed patch document: Can be specified using a 400 (Bad Request) 210 when the server finds that the patch document provided by the 211 client was not properly formatted. The definition of badly 212 formatted depends on the patch document chosen, but generally if 213 the server finds it cannot handle the patch due to the 214 serialization of the patch document, this response ought to be 215 appropriate. 216 Unsupported patch document: Can be specified using a 415 217 (Unsupported Media Type) when the client sends a patch document 218 format that the server does not support for the resource 219 identified by the Request-URI. Such a response SHOULD include an 220 Accept-Patch response header as described in Section 3.1 to notify 221 the client what patch document formats are supported. 222 Unprocessable request: Can be specified with a 422 (Unprocessable 223 Entity) ([RFC4918], Section 11.2) when the server understands the 224 patch document and the syntax of the patch document appears valid, 225 but the server is incapable of processing the request. This might 226 include attempts to modify a resource in a way that would cause 227 the resource to become invalid: for instance, a modification to a 228 well-formed XML document that would cause it to no longer be well- 229 formed. There may also be more specific errors like "Conflicting 230 State" that could be signaled with this status code, but the more 231 specific error would generally be more helpful. 232 Resource Not Found: Can be specified with a 404 (Not Found) status 233 code, when the client attempted to apply a patch document to a 234 non-existent resource, but the patch document chosen cannot be 235 applied to a non-existent resource. 236 Conflicting State: Can be specified with a 409 (Conflict) when the 237 request cannot be applied given the state of the resource. For 238 example, if the client attempted to apply a structural 239 modification and the structures assumed to exist did not exist 240 (with XML, a patch might specify changing element 'foo' to element 241 'bar' but element 'foo' might not exist). 242 Conflicting modification: Specified with a 412 (Precondition Failed) 243 when a client uses either the If-Match or If-Unmodified-Since 244 request headers and attempts to apply a patch document to a 245 resource whose state has changed since the patch was created. If 246 the server detects a possible conflicting modification and neither 247 the If-Match or If-Unmodified-Since request headers are used, the 248 server can return a 409 (Conflict) response. 249 Concurrent modification: When a server receives multiple concurrent 250 requests to modify a resource, those requests SHOULD be queued and 251 processed in the order in which they are received. If a server is 252 incapable of queuing concurrent requests, all subsequent requests 253 SHOULD be rejected with a 409 (Conflict) until the first 254 modification request is complete. 256 Other HTTP status codes can also be used under the appropriate 257 circumstances. 259 The entity body of error responses SHOULD contain enough information 260 to communicate the nature of the error to the client. The content- 261 type of the response entity can vary across implementations. 263 3. Advertising Support in OPTIONS 265 A server can advertise its support for the PATCH method by adding it 266 to the listing of allowed methods in the "Allow" OPTIONS response 267 header defined in HTTP/1.1. The PATCH method MAY appear in the 268 "Allow" header even if the Accept-Patch header is absent, in which 269 case the list of allowed patch documents is not advertised. 271 3.1. The Accept-Patch Header 273 This specification introduces a new response header "Accept-Patch" 274 used to specify the patch document formats accepted by the server. 275 "Accept-Patch" MUST appear in the OPTIONS response for any resource 276 that supports the use of the PATCH method. The presence of the 277 "Accept-Patch" header in response to any method is an implicit 278 indication that PATCH is allowed on the resource identified by the 279 Request-URI. The presence of a specific patch document format in 280 this header indicates that specific format is allowed on the resource 281 identified by the Request-URI. 283 Accept-Patch = "Accept-Patch" ":" 1#media-type 285 The Accept-Patch header specifies a comma separated listing of media- 286 types as defined by [RFC2616], Section 3.7. 288 3.2. Example OPTIONS Request and Response 290 [request] 292 OPTIONS /example/buddies.xml HTTP/1.1 293 Host: www.example.com 295 [response] 297 HTTP/1.1 200 OK 298 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 299 Accept-Patch: application/example, text/example 301 The examples show a server that supports PATCH generally using two 302 hypothetical patch document formats. 304 4. IANA Considerations 306 4.1. The 'Accept-Patch' Response Header 308 The 'Accept-Patch' response header should be added to the permanent 309 registry (see [RFC3864]). 311 Header field name: Accept-Patch 312 Applicable Protocol: HTTP 313 Author/Change controller: IETF 314 Specification document: this specification 316 5. Security Considerations 318 The security considerations for PATCH are nearly identical to the 319 security considerations for PUT ([RFC2616], Section 9.6). These 320 include authorizing requests (possibly through access control and/or 321 authentication) and ensuring that data is not corrupted through 322 transport errors or through accidental overwrites. Whatever 323 mechanisms are used for PUT can be used for PATCH as well. The 324 following considerations apply specially to PATCH. 326 A document that is patched might be more likely to be corrupted than 327 a document that is overridden in entirety, but that concern can be 328 addressed through the use of mechanisms such as conditional requests 329 using ETags and the If-Match request header. 331 Sometimes an HTTP intermediary might try to detect viruses being sent 332 via HTTP by checking the body of the PUT/POST request or GET 333 response. The PATCH method complicates such watch-keeping because 334 neither the source document nor the patch document might be a virus, 335 yet the result could be. This security consideration is not 336 materially different from those already introduced by byte-range 337 downloads, downloading patch documents, uploading zipped (compressed) 338 files and so on. 340 Individual patch documents will have their own specific security 341 considerations that will likely vary depending on the types of 342 resources being patched. The considerations for patched binary 343 resources, for instance, will be different than those for patched XML 344 documents. Servers MUST take adequate precautions to ensure that 345 malicious clients cannot consume excessive server resources (e.g., 346 CPU, disk I/O) through the client's use of PATCH. 348 6. References 350 6.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 6.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 and also 372 appears in Section 19.6.1.1 of RFC 2068. 374 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 375 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 376 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham, Michael 377 Balloni and Cyrus Daboo for review and advice on this document. 379 Appendix B. Changes 381 B.1. Changes from -00 383 OPTIONS support: removed "Patch" header definition and used Allow and 384 new "Accept-Patch" headers instead. 386 Supported delta encodings: removed vcdiff and diffe as these do not 387 have defined MIME types and did not seem to be strongly desired. 389 PATCH method definition: Clarified cache behavior. 391 B.2. Changes from -01 393 Removed references to XCAP - not yet a RFC. 395 Fixed use of MIME types (this "fix" now obsolete) 397 Explained how to use MOVE or COPY in conjunction with PATCH, to 398 create a new resource based on an existing resource in a different 399 location. 401 B.3. Changes from -02 403 Clarified that MOVE and COPY are really independent of PATCH. 405 Clarified when an ETag must change, and when Last-Modified must be 406 used. 408 Clarified what server should do if both Content-Type and IM headers 409 appear in PATCH request. 411 Filled in missing reference to DeltaV and ACL RFCs. 413 Stopped using 501 Unsupported for unsupported delta encodings. 415 Clarified what a static resource is. 417 Refixed use of MIME types for patch formats. 419 Limited the scope of some restrictions to apply only to usage of 420 required diff format. 422 B.4. Changes from -03 424 Various typographical, terminology consistency, and other minor 425 clarifications or fixes. 427 B.5. Changes from -04 429 Moved paragraphs on ACL and RFC3229 interoperability to new section. 431 Added security considerations. 433 Added IANA considerations, registration of new namespace, and 434 discontinued use of "DAV:" namespace for new elements. 436 Added example of error response. 438 B.6. Changes from -05 440 Due to various concerns it didn't seem likely the application/gdiff 441 registration could go through so switching to vcdiff as required diff 442 format, and to RFC3229's approach to specifying diff formats, 443 including use of the IM header. 445 Clarified what header server MUST use to return MD5 hash. 447 Reverted to using 501 Unsupported for unsupported delta encodings. 449 B.7. Changes from -06 451 The reliance on RFC 3229 defined patch documents has been factored 452 out in favor of delta encodings identified by MIME media type. 454 The required use of DeltaV-based error reporting has been removed in 455 favor of using basic HTTP status codes to report error conditions. 457 The Accept-Patch response header has been redefined as a listing of 458 media-ranges, similar to the Accept request header. 460 Added James Snell as a co-author. 462 B.8. Changes from -07 464 Terminology change from "delta encoding" to "patch document" 466 Added clarification on the safety and idempotency of PATCH 468 Updated the caching rules of PATCH responses 470 200 responses MUST include a representation of the modified resource. 471 204 responses are used to indicate successful response without 472 returning a representation. 474 Suggest using 422 Unprocessable Entity to indicate that a properly 475 formatted patch document cannot be processed 477 Clarify the use of 412 and 409 to indicate concurrent and conflicting 478 resource modifications. 480 Added registration for the Accept-Patch header. 482 Relaxed the requirements for the use of If-Match and If-Unmodified- 483 Since. 485 Add language that clarifies the difference between PUT and PATCH. 487 Add language that clarifies the issues with PATCH and Content 488 Negotiation. 490 Use of Accept-Patch on any response implies that PATCH is supported. 492 Add language advising caution when pipelining PATCH requests. 494 B.9. Changes from -08 496 Addition of the 209 Content Returned status code 498 Addition of the Prefer header field mechanism 500 Removed the paragraph discussing the use of 200+Content-Location. 501 This is replaced by the 209 Content Returned status code. 503 B.10. Changes from -09 505 Move the prefer header to a separate document 507 Restructure the document sections. 509 B.11. Changes from -10 511 Remove paragraph about pipelined requests. This is covered 512 adequately by RFC2616. 514 Remove paragraph about content negotiation. This is covered 515 adequately by RFC2616. 517 Explicitly indicate that PATCH can be used to create new resources. 519 Remove recommendation for servers to provide strong etags. This is 520 recommendation is implied and does not need to be explicitly. 522 Change Allow-Patch to a listing of media-type and not media-range. 524 B.12. Changes from -11 526 Fix section links. 528 State that this uses RFC2616-style ABNF. 530 Fix grammar for Accept-Patch. 532 Remove requirements for handling entity-headers on PATCH and replace 533 with general discussion of issues and consequences of having no 534 handling requirements. 536 Update Security Considerations to make it clear what security 537 considerations for PUT are, for comparison. 539 B.13. Changes from -12 541 Remove status 209 again. 543 Add security consideration about using too much server resources. 545 Remove Content-MD5 from example. 547 B.14. Changes from -13 549 Remove '*' value from Accept-Patch again. 551 Allow caching but only if context is clear. 553 Clarify how some patch formats might allow creating a new document. 555 Add comparison of PATCH to POST 557 Appendix C. Notes to RFC Editor 559 The RFC Editor should remove this section and the Changes section. 561 Authors' Addresses 563 Lisa Dusseault 564 Messaging Architects 565 180 Peel Street, Suite 333 566 Montreal, QC H3C 2G7 567 Canada 569 Email: lisa.dusseault@messagingarchitects.com 571 James M. Snell 573 Email: jasnell@gmail.com 574 URI: http://www.snellspace.com