idnits 2.17.1 draft-dusseault-http-patch-11.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 541. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 552. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 559. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 565. 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 (January 3, 2008) is 5958 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: July 6, 2008 J. Snell 5 January 3, 2008 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-11 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 July 6, 2008. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2008). 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 . . . . . . . . . . . . . . . . . . 4 51 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 52 3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6 53 3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . 7 58 5.2. HTTP Status codes . . . . . . . . . . . . . . . . . . . . 8 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 60 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . . . 10 72 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 73 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11 74 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 11 75 B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 12 76 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 12 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 78 Intellectual Property and Copyright Statements . . . . . . . . . . 13 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 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. If the Request-URI 102 does not point to an existing resource, and that URI is capable of 103 being defined as a new resource by the requesting user agent, the 104 origin server can create the resource with that URI. 106 The difference between the PUT and PATCH requests is reflected in the 107 way the server processes the enclosed entity to modify the resource 108 identified by the Request-URI. In a PUT request, the enclosed entity 109 is considered to be a modified version of the resource stored on the 110 origin server and the client is requesting that the stored version be 111 replaced. With PATCH, however, the enclosed entity contains a set of 112 instructions describing how a resource currently residing on the 113 origin server should be modified to produce a new version. The 114 changes described by the entity MAY result in the creation of one or 115 more new resources on the server, however it is not intended that the 116 body of the PATCH request be used as the content of such resources. 118 The server MUST apply the entire set of changes atomically and never 119 provide (e.g. in response to a GET during this operation) a 120 partially-modified representation. If the entire patch document 121 cannot be successfully applied then the server MUST fail the entire 122 request, applying none of the changes. The determination of what 123 constitutes a successful PATCH can vary depending on the patch 124 document and the type of resource being modified. The actual method 125 for determining how to apply the patch document to the resource is 126 defined entirely by the origin server. See Error Handling in section 127 2.2 for details on status codes and possible error conditions. 129 If the request passes through a cache and the Request-URI identifies 130 one or more currently cached entities, those entries SHOULD be 131 treated as stale. Responses to this method are not cacheable, unless 132 the response includes appropriate Cache-Control or Expires header 133 fields or the response uses the 209 Content Returned status code as 134 defined in Section 4. The 303 (See Other) response can be used to 135 direct the user agent to retrieve a cacheable resource. 137 Collisions from multiple requests are more dangerous than PUT 138 collisions, because a patch document that is not operating from a 139 known base point may corrupt the resource. Clients wishing to apply 140 a patch document to a known entity can first acquire the strong ETag 141 of the resource to be modified, and use that Etag in the If-Match 142 header on the PATCH request to verify that the resource is still 143 unchanged. If a strong ETag is not available for a given resource, 144 the client can use If-Unmodified-Since as a less-reliable safeguard. 146 It is RECOMMENDED that servers return a 501 (Not Implemented) 147 response if a PATCH request contains any entity-headers the server 148 does not understand. Unexpected or unintended results can occur if a 149 server ignores known or unknown entity headers included in the 150 request. All entity-headers contained in the request apply only to 151 the contained patch document and MUST NOT be applied to the resource 152 being modified. 154 There is no guarantee that a resource can be modified with PATCH. 155 Further, it is expected that different patch document formats will be 156 appropriate for different types of resources and that no single 157 format will be appropriate for all types of resources. Therefore, 158 there is no single default patch document format that implementations 159 are required to support. Servers MUST ensure that a received patch 160 document is appropriate for the type of resource identified by the 161 Request-URI. 163 2.1. A simple PATCH example 165 PATCH /file.txt HTTP/1.1 166 Host: www.example.com 167 Content-type: application/example 168 If-Match: "e0023aa4e" 169 Content-Length: 100 171 [description of changes] 173 This example illustrates use of a hypothetical patch document on an 174 existing resource. 176 Successful PATCH response to existing text file 178 HTTP/1.1 204 No Content 179 ETag: "e0023aa4f" 180 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 182 2.2. Error handling 184 There are several known conditions under which a PATCH request can 185 fail. 187 Malformed patch document: Can be specified using a 400 Bad Request 188 when the server finds that the patch document provided by the 189 client was not properly formatted. The definition of badly 190 formatted depends on the patch document chosen, but generally if 191 the server finds it cannot handle the patch due to the 192 serialization of the patch document, this response ought to be 193 appropriate. 194 Unsupported patch document: Can be Specified using a 415 Unsupported 195 Media Type when the client sends a patch document format that the 196 server does not support for the resource identified by the 197 Request-URI. Such a response SHOULD include an Accept-Patch 198 response header as described in Section 3.1 to notify the client 199 what patch document formats are supported. 200 Unprocessable request: Can be specified with a 422 Unprocessable 201 Entity [RFC4918] when the server understands the patch document 202 and the syntax of the patch document appears valid, but the server 203 is incapable of processing the request. There are a number of 204 situations that could lead to such a result, for example: 205 * The client attempted to apply a patch document to an empty or 206 non-existent resource, but the patch document chosen cannot be 207 applied to an empty or non-existent resource. 208 * The client attempted to apply a structural modification and the 209 structures assumed to exist did not exist (e.g. a patch which 210 specifies changing element 'foo' to element 'bar' but element 211 'foo' doesn't exist). 212 * The client attempted to modify a resource in a way that would 213 cause the resource to become invalid. For instance, a 214 modification to a well-formed XML document that would cause it 215 to no longer be well-formed. 216 * The client attempted to modify a resource that has multiple 217 representations but the server was unable to choose which 218 representation to modify. 219 Conflicting modification: Specified with a 412 Precondition Failed 220 when a client uses either the If-Match or If-Unmodified-Since 221 request headers and attempts to apply a patch document to a 222 resource whose state has changed since the patch was created. If 223 the server detects a possible conflicting modification and neither 224 the If-Match or If-Unmodified-Since request headers are used, the 225 server can return a 409 Conflict response. 226 Concurrent modification: When a server receives multiple concurrent 227 requests to modify a resource, those requests SHOULD be queued and 228 processed in the order in which they are received. If a server is 229 incapable of queuing concurrent requests, all subsequent requests 230 SHOULD be rejected with a 409 Conflict until the first 231 modification request is complete. 233 Other HTTP status codes can also be used under the appropriate 234 circumstances. 236 The entity body of error responses SHOULD contain enough information 237 to communicate the nature of the error to the client. The content- 238 type of the response entity can vary across implementations. 240 3. Advertising Support in OPTIONS 242 A server can advertise its support for the PATCH method by adding it 243 to the listing of allowed methods in the "Allow" OPTIONS response 244 header defined in HTTP/1.1. 246 3.1. The Accept-Patch Header 248 Clients also need to know whether the server supports specific patch 249 document formats, so this specification introduces a new response 250 header "Accept-Patch" used to specify the patch document formats 251 accepted by the server. "Accept-Patch" MUST appear in the OPTIONS 252 response for any resource that supports the use of the PATCH method. 253 The presence of the "Accept-Patch" header in response to any method 254 is an implicit indication that PATCH is allowed on the resource 255 identified by the Request-URI. 257 Accept-Patch = "Accept-Patch" ":" "*" | #( media-type ) 259 The Accept-Patch header specifies a comma separated listing of media- 260 types as defined by [RFC2616], Section 3.7. The asterisk character 261 "*" MAY be used to indicate that any patch format is accepted. 263 3.2. An example OPTIONS request and response 265 [request] 267 OPTIONS /example/buddies.xml HTTP/1.1 268 Host: www.example.com 270 [response] 272 HTTP/1.1 200 OK 273 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 274 Accept-Patch: application/example, text/example 276 The examples show a server that supports PATCH generally using two 277 hypothetical patch document formats. 279 4. 209 Content Returned 281 The 209 "Content Returned" status code can be used to indicate that a 282 response is equivalent to what would have been returned with a 200 283 status code response to a GET sent to the URI immediately following 284 the successful completion of the request. 286 5. IANA Considerations 288 5.1. The 'Accept-Patch' Response Header 290 The 'Accept-Patch' response header should be added to the permanent 291 registry (see [RFC3864]). 293 Header field name: Accept-Patch 295 Applicable Protocol: HTTP 297 Status: standard 299 Author/Change controller: IETF 301 Specification document: this specification 303 5.2. HTTP Status codes 305 This specification defines the 209 Content Returned status code 306 (Section 3) to be updated in the registry at 307 . 309 6. Security Considerations 311 The security considerations for PATCH are nearly identical to the 312 security considerations for PUT. In addition, one might be concerned 313 that a document that is patched might be more likely to be corrupted, 314 but that concern can be addressed through the use of mechanisms such 315 as conditional requests using ETags and the If-Match request header. 317 Sometimes an HTTP intermediary might try to detect viruses being sent 318 via HTTP by checking the body of the PUT/POST request or GET 319 response. The PATCH method complicates such watch-keeping because 320 neither the source document nor the patch document might be a virus, 321 yet the result could be. This security consideration is not 322 materially different from those already introduced by byte-range 323 downloads, downloading patch documents, uploading zipped (compressed) 324 files and so on. 326 Individual patch documents will have their own specific security 327 considerations that will likely vary depending on the types of 328 resources being patched. The considerations for patched binary 329 resources, for instance, will be different than those for patched XML 330 documents. 332 7. References 334 7.1. Normative References 336 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 337 Requirement Levels", BCP 14, RFC 2119, March 1997. 339 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 340 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 341 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 343 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 344 Procedures for Message Header Fields", BCP 90, RFC 3864, 345 September 2004. 347 7.2. Informative References 349 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 350 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 352 Appendix A. Acknowledgements 354 PATCH is not a new concept, it first appeared in HTTP in drafts of 355 version 1.1 written by Roy Fielding and Henrik Frystyk. 357 Thanks to Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott 358 Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex 359 Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham and Michael 360 Balloni for review and advice on this document. 362 Appendix B. Changes 364 B.1. Changes from -00 366 OPTIONS support: removed "Patch" header definition and used Allow and 367 new "Accept-Patch" headers instead. 369 Supported delta encodings: removed vcdiff and diffe as these do not 370 have defined MIME types and did not seem to be strongly desired. 372 PATCH method definition: Clarified cache behavior. 374 B.2. Changes from -01 376 Removed references to XCAP - not yet a RFC. 378 Fixed use of MIME types (this "fix" now obsolete) 380 Explained how to use MOVE or COPY in conjunction with PATCH, to 381 create a new resource based on an existing resource in a different 382 location. 384 B.3. Changes from -02 386 Clarified that MOVE and COPY are really independent of PATCH. 388 Clarified when an ETag must change, and when Last-Modified must be 389 used. 391 Clarified what server should do if both Content-Type and IM headers 392 appear in PATCH request. 394 Filled in missing reference to DeltaV and ACL RFCs. 396 Stopped using 501 Unsupported for unsupported delta encodings. 398 Clarified what a static resource is. 400 Refixed use of MIME types for patch formats. 402 Limited the scope of some restrictions to apply only to usage of 403 required diff format. 405 B.4. Changes from -03 407 Various typographical, terminology consistency, and other minor 408 clarifications or fixes. 410 B.5. Changes from -04 412 Moved paragraphs on ACL and RFC3229 interoperability to new section. 414 Added security considerations. 416 Added IANA considerations, registration of new namespace, and 417 discontinued use of "DAV:" namespace for new elements. 419 Added example of error response. 421 B.6. Changes from -05 423 Due to various concerns it didn't seem likely the application/gdiff 424 registration could go through so switching to vcdiff as required diff 425 format, and to RFC3229's approach to specifying diff formats, 426 including use of the IM header. 428 Clarified what header server MUST use to return MD5 hash. 430 Reverted to using 501 Unsupported for unsupported delta encodings. 432 B.7. Changes from -06 434 The reliance on RFC 3229 defined patch documents has been factored 435 out in favor of delta encodings identified by MIME media type. 437 The required use of DeltaV-based error reporting has been removed in 438 favor of using basic HTTP status codes to report error conditions. 440 The Accept-Patch response header has been redefined as a listing of 441 media-ranges, similar to the Accept request header. 443 Added James Snell as a co-author. 445 B.8. Changes from -07 447 Terminology change from "delta encoding" to "patch document" 449 Added clarification on the safety and idempotency of PATCH 451 Updated the caching rules of PATCH responses 453 200 responses MUST include a representation of the modified resource. 454 204 responses are used to indicate successful response without 455 returning a representation. 457 Suggest using 422 Unprocessable Entity to indicate that a properly 458 formatted patch document cannot be processed 460 Clarify the use of 412 and 409 to indicate concurrent and conflicting 461 resource modifications. 463 Added registration for the Accept-Patch header. 465 Relaxed the requirements for the use of If-Match and If-Unmodified- 466 Since. 468 Add language that clarifies the difference between PUT and PATCH. 470 Add language that clarifies the issues with PATCH and Content 471 Negotiation. 473 Use of Accept-Patch on any response implies that PATCH is supported. 475 Add language advising caution when pipelining PATCH requests. 477 B.9. Changes from -08 479 Addition of the 209 Content Returned status code 481 Addition of the Prefer header field mechanism 483 Removed the paragraph discussing the use of 200+Content-Location. 484 This is replaced by the 209 Content Returned status code. 486 B.10. Changes from -09 488 Move the prefer header to a separate document 490 Restructure the document sections. 492 B.11. Changes from -10 494 Remove paragraph about pipelined requests. This is covered 495 adequately by RFC2616. 497 Remove paragraph about content negotiation. This is covered 498 adequately by RFC2616. 500 Explicitly indicate that PATCH can be used to create new resources. 502 Remove recommendation for servers to provide strong etags. This is 503 recommendation is implied and does not need to be explicitly. 505 Change Allow-Patch to a listing of media-type and not media-range. 507 Appendix C. Notes to RFC Editor 509 The RFC Editor should remove this section and the Changes section. 511 Authors' Addresses 513 Lisa Dusseault 514 Open Source Application Foundation 515 2064 Edgewood Dr. 516 Palo Alto, CA 94303 517 US 519 Email: lisa@osafoundation.org 521 James M Snell 523 Phone: 524 Email: jasnell@gmail.com 525 URI: http://www.snellspace.com 527 Full Copyright Statement 529 Copyright (C) The IETF Trust (2008). 531 This document is subject to the rights, licenses and restrictions 532 contained in BCP 78, and except as set forth therein, the authors 533 retain all their rights. 535 This document and the information contained herein are provided on an 536 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 537 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 538 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 539 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 540 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 541 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 543 Intellectual Property 545 The IETF takes no position regarding the validity or scope of any 546 Intellectual Property Rights or other rights that might be claimed to 547 pertain to the implementation or use of the technology described in 548 this document or the extent to which any license under such rights 549 might or might not be available; nor does it represent that it has 550 made any independent effort to identify any such rights. Information 551 on the procedures with respect to rights in RFC documents can be 552 found in BCP 78 and BCP 79. 554 Copies of IPR disclosures made to the IETF Secretariat and any 555 assurances of licenses to be made available, or the result of an 556 attempt made to obtain a general license or permission for the use of 557 such proprietary rights by implementers or users of this 558 specification can be obtained from the IETF on-line IPR repository at 559 http://www.ietf.org/ipr. 561 The IETF invites any interested party to bring to its attention any 562 copyrights, patents or patent applications, or other proprietary 563 rights that may cover technology that may be required to implement 564 this standard. Please address the information to the IETF at 565 ietf-ipr@ietf.org. 567 Acknowledgment 569 Funding for the RFC Editor function is provided by the IETF 570 Administrative Support Activity (IASA).