idnits 2.17.1 draft-dusseault-http-patch-10.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 555. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 566. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 573. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 579. 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 (October 27, 2007) is 6019 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: April 29, 2008 J. Snell 5 October 27, 2007 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-10 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 April 29, 2008. 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. The PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3 50 2.1. A simple PATCH example . . . . . . . . . . . . . . . . . . 5 51 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 52 3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6 53 3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 7 54 3.2. An example OPTIONS request and response . . . . . . . . . 7 55 4. 209 Content Returned . . . . . . . . . . . . . . . . . . . . . 7 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 57 5.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 8 58 5.2. HTTP Status codes . . . . . . . . . . . . . . . . . . . . 8 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 60 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 7.1. Normative References . . . . . . . . . . . . . . . . . . . 9 62 7.2. Informative References . . . . . . . . . . . . . . . . . . 9 63 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 64 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9 65 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9 66 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9 67 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 10 68 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10 69 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10 70 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10 71 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 11 72 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 73 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 12 74 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 12 75 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 12 76 Appendix D. Editorial Notes . . . . . . . . . . . . . . . . . . . 12 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 78 Intellectual Property and Copyright Statements . . . . . . . . . . 14 80 1. Introduction 82 This specification defines the new HTTP 1.1 [RFC2616] method PATCH 83 that is used to apply partial modifications to a HTTP resource. 85 A new method is necessary to improve interoperability and prevent 86 errors. The PUT method is already defined to overwrite a resource 87 with a complete new body, and can not be reused to do partial 88 changes. Otherwise, proxies and caches and even clients and servers 89 may get confused as to the result of the operation. 91 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 92 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 93 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 95 2. The PATCH Method 97 The PATCH method requests that a set of changes described in the 98 request entity be applied to the resource identified by the Request- 99 URI. The set of changes is represented in a format called a "patch 100 document" identified by a media type. PATCH is neither safe or 101 idempotent as defined by [RFC2616] Section 9.1. 103 The difference between the PUT and PATCH requests is reflected in the 104 way the server processes the enclosed entity to modify the resource 105 identified by the Request-URI. In a PUT request, the enclosed entity 106 is considered to be a modified version of the resource stored on the 107 origin server and the client is requesting that stored version be 108 replaced. With PATCH, however, the enclosed entity contains a set of 109 instructions describing how a resource currently residing on the 110 origin server should be modified to produce a new version. The 111 changes described by the entity MAY result in the creation of one or 112 more new resources on the server, however it is not intended that the 113 body of the PATCH request be used as the content of such resources. 115 The server MUST always apply the entire set of changes atomically and 116 never provide (e.g. in response to a GET during this operation) a 117 partially-modified representation. If the entire patch document 118 cannot be successfully applied then the server MUST fail the entire 119 request, applying none of the changes. The determination of what 120 constitutes a successful PATCH can vary depending on the patch 121 document and the type of resource being modified. The actual method 122 for determining how to apply the patch document to the resource is 123 defined entirely by the origin server. See Error Handling in section 124 2.2 for details on status codes and possible error conditions. 126 If the request passes through a cache and the Request-URI identifies 127 one or more currently cached entities, those entries SHOULD be 128 treated as stale. Responses to this method are not cacheable, unless 129 the response includes appropriate Cache-Control or Expires header 130 fields or the response uses the 209 Content Returned status code as 131 defined in Section 4. The 303 (See Other) response can be used to 132 direct the user agent to retrieve a cacheable resource. 134 Collisions from multiple requests are more dangerous than PUT 135 collisions, because a patch document that is not operating from a 136 known base point may corrupt the resource. Clients wishing to apply 137 a patch document to a known entity can first acquire the strong ETag 138 of the resource to be modified, and use that Etag in the If-Match 139 header on the PATCH request to verify that the resource is still 140 unchanged. If a strong ETag is not available for a given resource, 141 the client can use If-Unmodified-Since as a less-reliable safeguard. 143 It is RECOMMENDED that Servers provide strong ETags for all resources 144 for which PATCH is supported. 146 If a PATCH request contains any entity-headers the server does not 147 understand, the server MUST return a 501 (Not Implemented) response. 148 A server that understands a particular entity-header can choose to 149 ignore it; however, doing so can produce results that are unexpected 150 or unintended by the client. All entity-headers contained in the 151 request apply only to the contained patch document and MUST NOT be 152 applied to the resource being modified. 154 If the Request-URI identifies a resource with multiple alternate 155 representations, the server can choose to respond in a variety of 156 ways. For instance, the server can decide which representation to 157 alter and might even be able to change them all consistently 158 depending on the patch format. A particular patch document might be 159 able to identify specific representations to modify or might be 160 capable of describing changes to multiple representations. If the 161 server cannot choose a representation, it can reject the request with 162 an error or the server can choose to redirect the request (e.g. using 163 301 Moved Permanently or 302 Found), in which case the user agent 164 makes its own decision regarding whether or not to proceed with the 165 request. 167 Clients are advised to take caution when sending multiple PATCH 168 requests, or sequences of requests that include PATCH, over a 169 pipelined connection as there are no guarantees that pipelined 170 requests will be processed by the server in the same order in which 171 the client sends them. Such sequences of requests can be made safer 172 by using conditional request mechanisms such as If-Match. See 173 [RFC2616] Section 8.1.2.2 for additional details regarding pipelining 174 and non-idempotent requests. 176 There is no guarantee that a resource can be modified with PATCH. 177 Further, it is expected that different patch document formats will be 178 appropriate for different types of resources and that no single 179 format will be appropriate for all types of resources. Therefore, 180 there is no single default patch document format that implementations 181 are required to support. Servers MUST ensure that a received patch 182 document is appropriate for the type of resource identified by the 183 Request-URI. 185 2.1. A simple PATCH example 187 PATCH /file.txt HTTP/1.1 188 Host: www.example.com 189 Content-type: application/example 190 If-Match: "e0023aa4e" 191 Content-Length: 100 193 [description of changes] 195 This example illustrates use of a hypothetical patch document on an 196 existing resource. 198 Successful PATCH response to existing text file 200 HTTP/1.1 204 No Content 201 ETag: "e0023aa4f" 202 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 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 improperly 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: Specified using a 415 Unsupported Media 217 Type when the client uses a patch document format that the server 218 does not support for the resource identified by the Request-URI. 219 Such a response SHOULD include an Accept-Patch response header as 220 described in Section 3.1 to notify the client what patch document 221 formats are supported. 223 Unprocessable request: Can be specified with a 422 Unprocessable 224 Entity [RFC4918] when the server understands the patch document 225 and the syntax of the patch document appears valid, but the server 226 is incapable of processing the request. There are a number of 227 situations that could lead to such a result, for example: 228 * The client attempted to apply a patch document to an empty 229 resource, but the patch document chosen cannot be applied to an 230 empty resource. 231 * The client attempted to apply a structural modification and the 232 structures assumed to exist did not exist (e.g. a patch which 233 specifies changing element 'foo' to element 'bar' but element 234 'foo' doesn't exist). 235 * The client attempted to modify a resource in a way that would 236 cause the resource to become invalid. For instance, a 237 modification to a well-formed XML document that would cause it 238 to no longer be well-formed. 239 * The client attempted to modify a resource that has multiple 240 representations but the server was unable to choose which 241 representation to modify. 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 until the first modification request is 254 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. 269 3.1. The Accept-Patch Header 271 Clients also need to know whether the server supports specific patch 272 document formats, so this specification introduces a new response 273 header "Accept-Patch" used to specify the patch document formats 274 accepted by the server. "Accept-Patch" MUST appear in the OPTIONS 275 response for any resource that supports the use of the PATCH method. 276 The presence of the "Accept-Patch" header in response to any method 277 is an implicit indication that PATCH is allowed on the resource 278 identified by the Request-URI. 280 Accept-Patch = "Accept-Patch" ":" #( media-range ) 282 The Accept-Patch header specifies a listing of media ranges as 283 defined by [RFC2616], Section 14.1. Note that, unlike the HTTP 284 Accept request header, the Accept-Patch header does not use quality 285 factors. 287 3.2. An example OPTIONS request and response 289 [request] 291 OPTIONS /example/buddies.xml HTTP/1.1 292 Host: www.example.com 294 [response] 296 HTTP/1.1 200 OK 297 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 298 Accept-Patch: application/example, text/example 300 The examples show a server that supports PATCH generally using two 301 hypothetical patch documents. 303 4. 209 Content Returned 305 The 209 "Content Returned" status code can be used to indicate that a 306 response is equivalent to what would have been returned with a 200 307 status code response to a GET sent to the URI immediately following 308 the successful completion of the request. 310 5. IANA Considerations 311 5.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 5.2. HTTP Status codes 328 This specification defines the 209 Content Returned status code 329 (Section 3) to be updated in the registry at 330 . 332 6. Security Considerations 334 The security considerations for PATCH are nearly identical to the 335 security considerations for PUT. In addition, one might be concerned 336 that a document that is patched might be more likely to be corrupted, 337 but that concern can be addressed through the use of mechanisms such 338 as conditional requests 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. 355 7. References 356 7.1. Normative References 358 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 359 Requirement Levels", BCP 14, RFC 2119, March 1997. 361 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 362 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 363 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 365 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 366 Procedures for Message Header Fields", BCP 90, RFC 3864, 367 September 2004. 369 7.2. Informative References 371 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 372 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 374 Appendix A. Acknowledgements 376 PATCH is not a new concept, it first appeared in HTTP in drafts of 377 version 1.1 written by Roy Fielding and Henrik Frystyk. 379 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 380 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 381 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham and Michael 382 Balloni for review and advice on this document. 384 Appendix B. Changes 386 B.1. Changes from -00 388 OPTIONS support: removed "Patch" header definition and used Allow and 389 new "Accept-Patch" headers instead. 391 Supported delta encodings: removed vcdiff and diffe as these do not 392 have defined MIME types and did not seem to be strongly desired. 394 PATCH method definition: Clarified cache behavior. 396 B.2. Changes from -01 398 Removed references to XCAP - not yet a RFC. 400 Fixed use of MIME types (this "fix" now obsolete) 401 Explained how to use MOVE or COPY in conjunction with PATCH, to 402 create a new resource based on an existing resource in a different 403 location. 405 B.3. Changes from -02 407 Clarified that MOVE and COPY are really independent of PATCH. 409 Clarified when an ETag must change, and when Last-Modified must be 410 used. 412 Clarified what server should do if both Content-Type and IM headers 413 appear in PATCH request. 415 Filled in missing reference to DeltaV and ACL RFCs. 417 Stopped using 501 Unsupported for unsupported delta encodings. 419 Clarified what a static resource is. 421 Refixed use of MIME types for patch formats. 423 Limited the scope of some restrictions to apply only to usage of 424 required diff format. 426 B.4. Changes from -03 428 Various typographical, terminology consistency, and other minor 429 clarifications or fixes. 431 B.5. Changes from -04 433 Moved paragraphs on ACL and RFC3229 interoperability to new section. 435 Added security considerations. 437 Added IANA considerations, registration of new namespace, and 438 discontinued use of "DAV:" namespace for new elements. 440 Added example of error response. 442 B.6. Changes from -05 444 Due to various concerns it didn't seem likely the application/gdiff 445 registration could go through so switching to vcdiff as required diff 446 format, and to RFC3229's approach to specifying diff formats, 447 including use of the IM header. 449 Clarified what header server MUST use to return MD5 hash. 451 Reverted to using 501 Unsupported for unsupported delta encodings. 453 B.7. Changes from -06 455 The reliance on RFC 3229 defined patch documents has been factored 456 out in favor of delta encodings identified by MIME media type. 458 The required use of DeltaV-based error reporting has been removed in 459 favor of using basic HTTP status codes to report error conditions. 461 The Accept-Patch response header has been redefined as a listing of 462 media-ranges, similar to the Accept request header. 464 Added James Snell as a co-author. 466 B.8. Changes from -07 468 Terminology change from "delta encoding" to "patch document" 470 Added clarification on the safety and idempotency of PATCH 472 Updated the caching rules of PATCH responses 474 200 responses MUST include a representation of the modified resource. 475 204 responses are used to indicate successful response without 476 returning a representation. 478 Suggest using 422 Unprocessable Entity to indicate that a properly 479 formatted patch document cannot be processed 481 Clarify the use of 412 and 409 to indicate concurrent and conflicting 482 resource modifications. 484 Added registration for the Accept-Patch header. 486 Relaxed the requirements for the use of If-Match and If-Unmodified- 487 Since. 489 Add language that clarifies the difference between PUT and PATCH. 491 Add language that clarifies the issues with PATCH and Content 492 Negotiation. 494 Use of Accept-Patch on any response implies that PATCH is supported. 496 Add language advising caution when pipelining PATCH requests. 498 B.9. Changes from -08 500 Addition of the 209 Content Returned status code 502 Addition of the Prefer header field mechanism 504 Removed the paragraph discussing the use of 200+Content-Location. 505 This is replaced by the 209 Content Returned status code. 507 B.10. Changes from -09 509 Move the prefer header to a separate document 511 Restructure the document sections. 513 Appendix C. Notes to RFC Editor 515 The RFC Editor should remove this section and the Changes section. 517 Appendix D. Editorial Notes 519 There are several outstanding issues with the Prefer section: 521 o Should the Prefer section be separated out into a separate I-D? 522 o We need to determine how new preference codes are created/ 523 registered 524 o Are warn-codes ok or do we need a new response header? 526 Authors' Addresses 528 Lisa Dusseault 529 Open Source Application Foundation 530 2064 Edgewood Dr. 531 Palo Alto, CA 94303 532 US 534 Email: lisa@osafoundation.org 535 James M Snell 537 Phone: 538 Email: jasnell@gmail.com 539 URI: http://www.snellspace.com 541 Full Copyright Statement 543 Copyright (C) The IETF Trust (2007). 545 This document is subject to the rights, licenses and restrictions 546 contained in BCP 78, and except as set forth therein, the authors 547 retain all their rights. 549 This document and the information contained herein are provided on an 550 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 551 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 552 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 553 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 554 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 555 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 557 Intellectual Property 559 The IETF takes no position regarding the validity or scope of any 560 Intellectual Property Rights or other rights that might be claimed to 561 pertain to the implementation or use of the technology described in 562 this document or the extent to which any license under such rights 563 might or might not be available; nor does it represent that it has 564 made any independent effort to identify any such rights. Information 565 on the procedures with respect to rights in RFC documents can be 566 found in BCP 78 and BCP 79. 568 Copies of IPR disclosures made to the IETF Secretariat and any 569 assurances of licenses to be made available, or the result of an 570 attempt made to obtain a general license or permission for the use of 571 such proprietary rights by implementers or users of this 572 specification can be obtained from the IETF on-line IPR repository at 573 http://www.ietf.org/ipr. 575 The IETF invites any interested party to bring to its attention any 576 copyrights, patents or patent applications, or other proprietary 577 rights that may cover technology that may be required to implement 578 this standard. Please address the information to the IETF at 579 ietf-ipr@ietf.org. 581 Acknowledgment 583 Funding for the RFC Editor function is provided by the IETF 584 Administrative Support Activity (IASA).