idnits 2.17.1 draft-dusseault-http-patch-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 (February 4, 2009) is 5561 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: 1 error (**), 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: August 8, 2009 February 4, 2009 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-13 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 August 8, 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 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. 45 Abstract 47 Several applications extending the Hypertext Transfer Protocol (HTTP) 48 require a feature to do partial resource modification. The existing 49 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 . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . . . . 10 78 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11 79 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 11 80 B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 11 81 B.12. Changes from -11 . . . . . . . . . . . . . . . . . . . . . 12 82 B.13. Changes from -12 . . . . . . . . . . . . . . . . . . . . . 12 83 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 12 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 86 1. Introduction 88 This specification defines the new HTTP/1.1 [RFC2616] method PATCH 89 that is used to apply partial modifications to a resource. 91 A new method is necessary to improve interoperability and prevent 92 errors. The PUT method is already defined to overwrite a resource 93 with a complete new body, and can not be reused to do partial 94 changes. Otherwise, proxies and caches and even clients and servers 95 may get confused as to the result of the operation. 97 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 98 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 99 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 101 Furthermore, this document uses the ABNF syntax defined in Section 102 2.1 of [RFC2616]. 104 2. The PATCH Method 106 The PATCH method requests that a set of changes described in the 107 request entity be applied to the resource identified by the Request- 108 URI. The set of changes is represented in a format called a "patch 109 document" identified by a media type. If the Request-URI does not 110 point to an existing resource, and that URI is capable of being 111 defined as a new resource by the requesting user agent, the origin 112 server can create the resource with that URI. 114 PATCH is neither safe or idempotent as defined by [RFC2616], Section 115 9.1. 117 The difference between the PUT and PATCH requests is reflected in the 118 way the server processes the enclosed entity to modify the resource 119 identified by the Request-URI. In a PUT request, the enclosed entity 120 is considered to be a modified version of the resource stored on the 121 origin server and the client is requesting that the stored version be 122 replaced. With PATCH, however, the enclosed entity contains a set of 123 instructions describing how a resource currently residing on the 124 origin server should be modified to produce a new version. The 125 changes described by the entity MAY result in the creation of one or 126 more new resources on the server, however it is not intended that the 127 body of the PATCH request be used as the content of such resources. 129 The server MUST apply the entire set of changes atomically and never 130 provide (e.g. in response to a GET during this operation) a 131 partially-modified representation. If the entire patch document 132 cannot be successfully applied then the server MUST fail the entire 133 request, applying none of the changes. The determination of what 134 constitutes a successful PATCH can vary depending on the patch 135 document and the type of resource being modified. The actual method 136 for determining how to apply the patch document to the resource is 137 defined entirely by the origin server. See Error Handling in 138 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 not cacheable. 145 Collisions from multiple requests are more dangerous than PUT 146 collisions, because a patch document that is not operating from a 147 known base point may corrupt the resource. Clients wishing to apply 148 a patch document to a known entity can first acquire the strong ETag 149 of the resource to be modified, and use that Etag in the If-Match 150 header on the PATCH request to verify that the resource is still 151 unchanged. If a strong ETag is not available for a given resource, 152 the client can use If-Unmodified-Since as a less-reliable safeguard. 154 Note that entity-headers contained in the request apply only to the 155 contained patch document and MUST NOT be applied to the resource 156 being modified. Thus, a Content-Language header could be present on 157 the request but it would only mean (for whatever that's worth) that 158 the patch document had a language. Servers SHOULD NOT store such 159 headers except as trace information, and SHOULD NOT use such header 160 values the same way they might be used on PUT requests. Therefore, 161 this document does not specify a way to modify a document's Content- 162 Type or Content-Language value through headers, though a mechanism 163 could well be designed to achieve this goal through a patch document. 165 There is no guarantee that a resource can be modified with PATCH. 166 Further, it is expected that different patch document formats will be 167 appropriate for different types of resources and that no single 168 format will be appropriate for all types of resources. Therefore, 169 there is no single default patch document format that implementations 170 are required to support. Servers MUST ensure that a received patch 171 document is appropriate for the type of resource identified by the 172 Request-URI. 174 Clients need to choose when to use PATCH rather than PUT. For 175 example, if the patch document size is larger than the size of the 176 new resource data that would be used in a PUT, then it might make 177 sense to use PUT instead of PATCH. 179 2.1. A simple PATCH example 181 PATCH /file.txt HTTP/1.1 182 Host: www.example.com 183 Content-Type: application/example 184 If-Match: "e0023aa4e" 185 Content-Length: 100 187 [description of changes] 189 This example illustrates use of a hypothetical patch document on an 190 existing resource. 192 Successful PATCH response to existing text file 194 HTTP/1.1 204 No Content 195 ETag: "e0023aa4f" 197 2.2. Error handling 199 There are several known conditions under which a PATCH request can 200 fail. 202 Malformed patch document: Can be specified using a 400 (Bad Request) 203 when the server finds that the patch document provided by the 204 client was not properly formatted. The definition of badly 205 formatted depends on the patch document chosen, but generally if 206 the server finds it cannot handle the patch due to the 207 serialization of the patch document, this response ought to be 208 appropriate. 209 Unsupported patch document: Can be specified using a 415 210 (Unsupported Media Type) when the client sends a patch document 211 format that the server does not support for the resource 212 identified by the Request-URI. Such a response SHOULD include an 213 Accept-Patch response header as described in Section 3.1 to notify 214 the client what patch document formats are supported. 215 Unprocessable request: Can be specified with a 422 (Unprocessable 216 Entity) ([RFC4918], Section 11.2) when the server understands the 217 patch document and the syntax of the patch document appears valid, 218 but the server is incapable of processing the request. This might 219 include attempts to modify a resource in a way that would cause 220 the resource to become invalid: for instance, a modification to a 221 well-formed XML document that would cause it to no longer be well- 222 formed. 224 Resource Not Found: Can be specified with a 404 (Not Found) status 225 code, when the client attempted to apply a patch document to a 226 non-existent resource, but the patch document chosen cannot be 227 applied to a non-existent resource. 228 Conflicting State: Can be specified with a 409 (Conflict) when the 229 request cannot be applied given the state of the resource. For 230 example, if the client attempted to apply a structural 231 modification and the structures assumed to exist did not exist 232 (with XML, a patch might specify changing element 'foo' to element 233 'bar' but element 'foo' might not exist). 234 Conflicting modification: Specified with a 412 (Precondition Failed) 235 when a client uses either the If-Match or If-Unmodified-Since 236 request headers and attempts to apply a patch document to a 237 resource whose state has changed since the patch was created. If 238 the server detects a possible conflicting modification and neither 239 the If-Match or If-Unmodified-Since request headers are used, the 240 server can return a 409 (Conflict) response. 241 Concurrent modification: When a server receives multiple concurrent 242 requests to modify a resource, those requests SHOULD be queued and 243 processed in the order in which they are received. If a server is 244 incapable of queuing concurrent requests, all subsequent requests 245 SHOULD be rejected with a 409 (Conflict) until the first 246 modification request is complete. 248 Other HTTP status codes can also be used under the appropriate 249 circumstances. 251 The entity body of error responses SHOULD contain enough information 252 to communicate the nature of the error to the client. The content- 253 type of the response entity can vary across implementations. 255 3. Advertising Support in OPTIONS 257 A server can advertise its support for the PATCH method by adding it 258 to the listing of allowed methods in the "Allow" OPTIONS response 259 header defined in HTTP/1.1. 261 3.1. The Accept-Patch Header 263 Clients also need to know whether the server supports specific patch 264 document formats, so this specification introduces a new response 265 header "Accept-Patch" used to specify the patch document formats 266 accepted by the server. "Accept-Patch" MUST appear in the OPTIONS 267 response for any resource that supports the use of the PATCH method. 268 The presence of the "Accept-Patch" header in response to any method 269 is an implicit indication that PATCH is allowed on the resource 270 identified by the Request-URI. 272 Accept-Patch = "Accept-Patch" ":" ( "*" | #media-type ) 274 The Accept-Patch header specifies a comma separated listing of media- 275 types as defined by [RFC2616], Section 3.7. The asterisk character 276 "*" can be used to indicate that any patch format is accepted. 278 3.2. Example OPTIONS Request and Response 280 [request] 282 OPTIONS /example/buddies.xml HTTP/1.1 283 Host: www.example.com 285 [response] 287 HTTP/1.1 200 OK 288 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 289 Accept-Patch: application/example, text/example 291 The examples show a server that supports PATCH generally using two 292 hypothetical patch document formats. 294 4. IANA Considerations 296 4.1. The 'Accept-Patch' Response Header 298 The 'Accept-Patch' response header should be added to the permanent 299 registry (see [RFC3864]). 301 Header field name: Accept-Patch 302 Applicable Protocol: HTTP 303 Author/Change controller: IETF 304 Specification document: this specification 306 5. Security Considerations 308 The security considerations for PATCH are nearly identical to the 309 security considerations for PUT ([RFC2616], Section 9.6). These 310 include authorizing requests (possibly through access control and/or 311 authentication) and ensuring that data is not corrupted through 312 transport errors or through accidental overwrites. Whatever 313 mechanisms are used for PUT can be used for PATCH as well. The 314 following considerations apply specially to PATCH. 316 A document that is patched might be more likely to be corrupted than 317 a document that is overridden in entirety, but that concern can be 318 addressed through the use of mechanisms such as conditional requests 319 using ETags and the If-Match request header. 321 Sometimes an HTTP intermediary might try to detect viruses being sent 322 via HTTP by checking the body of the PUT/POST request or GET 323 response. The PATCH method complicates such watch-keeping because 324 neither the source document nor the patch document might be a virus, 325 yet the result could be. This security consideration is not 326 materially different from those already introduced by byte-range 327 downloads, downloading patch documents, uploading zipped (compressed) 328 files and so on. 330 Individual patch documents will have their own specific security 331 considerations that will likely vary depending on the types of 332 resources being patched. The considerations for patched binary 333 resources, for instance, will be different than those for patched XML 334 documents. Servers MUST take adequate precautions to ensure that 335 malicious clients cannot consume excessive server resources (e.g., 336 CPU, disk I/O) through the client's use of PATCH. 338 6. References 340 6.1. Normative References 342 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 343 Requirement Levels", BCP 14, RFC 2119, March 1997. 345 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 346 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 347 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 349 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 350 Procedures for Message Header Fields", BCP 90, RFC 3864, 351 September 2004. 353 6.2. Informative References 355 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 356 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 358 Appendix A. Acknowledgements 360 PATCH is not a new concept, it first appeared in HTTP in drafts of 361 version 1.1 written by Roy Fielding and Henrik Frystyk and also 362 appears in Section 19.6.1.1 of RFC 2068. 364 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 365 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 366 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham, Michael 367 Balloni and Cyrus Daboo for review and advice on this document. 369 Appendix B. Changes 371 B.1. Changes from -00 373 OPTIONS support: removed "Patch" header definition and used Allow and 374 new "Accept-Patch" headers instead. 376 Supported delta encodings: removed vcdiff and diffe as these do not 377 have defined MIME types and did not seem to be strongly desired. 379 PATCH method definition: Clarified cache behavior. 381 B.2. Changes from -01 383 Removed references to XCAP - not yet a RFC. 385 Fixed use of MIME types (this "fix" now obsolete) 387 Explained how to use MOVE or COPY in conjunction with PATCH, to 388 create a new resource based on an existing resource in a different 389 location. 391 B.3. Changes from -02 393 Clarified that MOVE and COPY are really independent of PATCH. 395 Clarified when an ETag must change, and when Last-Modified must be 396 used. 398 Clarified what server should do if both Content-Type and IM headers 399 appear in PATCH request. 401 Filled in missing reference to DeltaV and ACL RFCs. 403 Stopped using 501 Unsupported for unsupported delta encodings. 405 Clarified what a static resource is. 407 Refixed use of MIME types for patch formats. 409 Limited the scope of some restrictions to apply only to usage of 410 required diff format. 412 B.4. Changes from -03 414 Various typographical, terminology consistency, and other minor 415 clarifications or fixes. 417 B.5. Changes from -04 419 Moved paragraphs on ACL and RFC3229 interoperability to new section. 421 Added security considerations. 423 Added IANA considerations, registration of new namespace, and 424 discontinued use of "DAV:" namespace for new elements. 426 Added example of error response. 428 B.6. Changes from -05 430 Due to various concerns it didn't seem likely the application/gdiff 431 registration could go through so switching to vcdiff as required diff 432 format, and to RFC3229's approach to specifying diff formats, 433 including use of the IM header. 435 Clarified what header server MUST use to return MD5 hash. 437 Reverted to using 501 Unsupported for unsupported delta encodings. 439 B.7. Changes from -06 441 The reliance on RFC 3229 defined patch documents has been factored 442 out in favor of delta encodings identified by MIME media type. 444 The required use of DeltaV-based error reporting has been removed in 445 favor of using basic HTTP status codes to report error conditions. 447 The Accept-Patch response header has been redefined as a listing of 448 media-ranges, similar to the Accept request header. 450 Added James Snell as a co-author. 452 B.8. Changes from -07 454 Terminology change from "delta encoding" to "patch document" 456 Added clarification on the safety and idempotency of PATCH 458 Updated the caching rules of PATCH responses 459 200 responses MUST include a representation of the modified resource. 460 204 responses are used to indicate successful response without 461 returning a representation. 463 Suggest using 422 Unprocessable Entity to indicate that a properly 464 formatted patch document cannot be processed 466 Clarify the use of 412 and 409 to indicate concurrent and conflicting 467 resource modifications. 469 Added registration for the Accept-Patch header. 471 Relaxed the requirements for the use of If-Match and If-Unmodified- 472 Since. 474 Add language that clarifies the difference between PUT and PATCH. 476 Add language that clarifies the issues with PATCH and Content 477 Negotiation. 479 Use of Accept-Patch on any response implies that PATCH is supported. 481 Add language advising caution when pipelining PATCH requests. 483 B.9. Changes from -08 485 Addition of the 209 Content Returned status code 487 Addition of the Prefer header field mechanism 489 Removed the paragraph discussing the use of 200+Content-Location. 490 This is replaced by the 209 Content Returned status code. 492 B.10. Changes from -09 494 Move the prefer header to a separate document 496 Restructure the document sections. 498 B.11. Changes from -10 500 Remove paragraph about pipelined requests. This is covered 501 adequately by RFC2616. 503 Remove paragraph about content negotiation. This is covered 504 adequately by RFC2616. 506 Explicitly indicate that PATCH can be used to create new resources. 508 Remove recommendation for servers to provide strong etags. This is 509 recommendation is implied and does not need to be explicitly. 511 Change Allow-Patch to a listing of media-type and not media-range. 513 B.12. Changes from -11 515 Fix section links. 517 State that this uses RFC2616-style ABNF. 519 Fix grammar for Accept-Patch. 521 Remove requirements for handling entity-headers on PATCH and replace 522 with general discussion of issues and consequences of having no 523 handling requirements. 525 Update Security Considerations to make it clear what security 526 considerations for PUT are, for comparison. 528 B.13. Changes from -12 530 Remove status 209 again. 532 Add security consideration about using too much server resources. 534 Remove Content-MD5 from example. 536 Appendix C. Notes to RFC Editor 538 The RFC Editor should remove this section and the Changes section. 540 Authors' Addresses 542 Lisa Dusseault 543 Messaging Architects 544 180 Peel Street, Suite 333 545 Montreal, QC H3C 2G7 546 Canada 548 Email: lisa.dusseault@messagingarchitects.com 549 James M. Snell 551 Email: jasnell@gmail.com 552 URI: http://www.snellspace.com