idnits 2.17.1 draft-dusseault-http-patch-12.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 (January 19, 2009) is 5576 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: July 23, 2009 January 19, 2009 7 PATCH Method for HTTP 8 draft-dusseault-http-patch-12 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 July 23, 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 HTTP require a feature to do partial 48 resource modification. Existing HTTP functionality only allows a 49 complete replacement of a document. This proposal adds a new HTTP 50 method, PATCH, to modify an existing HTTP resource. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. The PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. A simple PATCH example . . . . . . . . . . . . . . . . . . 5 57 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 58 3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6 59 3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 6 60 3.2. An example OPTIONS request and response . . . . . . . . . 7 61 4. 209 Content Returned . . . . . . . . . . . . . . . . . . . . . 7 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 5.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 7 64 5.2. HTTP Status codes . . . . . . . . . . . . . . . . . . . . 7 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 68 7.2. Informative References . . . . . . . . . . . . . . . . . . 9 69 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 70 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9 71 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9 72 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9 73 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 9 74 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10 75 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10 76 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10 77 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 10 78 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 79 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11 80 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 12 81 B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 12 82 B.12. Changes from -11 . . . . . . . . . . . . . . . . . . . . . 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. PATCH is neither safe or 110 idempotent as defined by [RFC2616], Section 9.1. If the Request-URI 111 does not point to an existing resource, and that URI is capable of 112 being defined as a new resource by the requesting user agent, the 113 origin server can create the resource with that URI. 115 The difference between the PUT and PATCH requests is reflected in the 116 way the server processes the enclosed entity to modify the resource 117 identified by the Request-URI. In a PUT request, the enclosed entity 118 is considered to be a modified version of the resource stored on the 119 origin server and the client is requesting that the stored version be 120 replaced. With PATCH, however, the enclosed entity contains a set of 121 instructions describing how a resource currently residing on the 122 origin server should be modified to produce a new version. The 123 changes described by the entity MAY result in the creation of one or 124 more new resources on the server, however it is not intended that the 125 body of the PATCH request be used as the content of such resources. 127 The server MUST apply the entire set of changes atomically and never 128 provide (e.g. in response to a GET during this operation) a 129 partially-modified representation. If the entire patch document 130 cannot be successfully applied then the server MUST fail the entire 131 request, applying none of the changes. The determination of what 132 constitutes a successful PATCH can vary depending on the patch 133 document and the type of resource being modified. The actual method 134 for determining how to apply the patch document to the resource is 135 defined entirely by the origin server. See Error Handling in 136 Section 2.2 for details on status codes and possible error 137 conditions. 139 If the request passes through a cache and the Request-URI identifies 140 one or more currently cached entities, those entries SHOULD be 141 treated as stale. Responses to this method are not cacheable, unless 142 the response includes appropriate Cache-Control or Expires header 143 fields or the response uses the 209 Content Returned status code as 144 defined in Section 4. The 303 (See Other) response can be used to 145 direct the user agent to retrieve a cacheable resource. 147 Collisions from multiple 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 2.1. A simple PATCH example 178 PATCH /file.txt HTTP/1.1 179 Host: www.example.com 180 Content-Type: application/example 181 If-Match: "e0023aa4e" 182 Content-Length: 100 184 [description of changes] 186 This example illustrates use of a hypothetical patch document on an 187 existing resource. 189 Successful PATCH response to existing text file 191 HTTP/1.1 204 No Content 192 ETag: "e0023aa4f" 193 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ== 195 2.2. Error handling 197 There are several known conditions under which a PATCH request can 198 fail. 200 Malformed patch document: Can be specified using a 400 (Bad Request) 201 when the server finds that the patch document provided by the 202 client was not properly formatted. The definition of badly 203 formatted depends on the patch document chosen, but generally if 204 the server finds it cannot handle the patch due to the 205 serialization of the patch document, this response ought to be 206 appropriate. 207 Unsupported patch document: Can be Specified using a 415 208 (Unsupported Media Type) when the client sends a patch document 209 format that the server does not support for the resource 210 identified by the Request-URI. Such a response SHOULD include an 211 Accept-Patch response header as described in Section 3.1 to notify 212 the client what patch document formats are supported. 213 Unprocessable request: Can be specified with a 422 (Unprocessable 214 Entity) ([RFC4918], Section 11.2) when the server understands the 215 patch document and the syntax of the patch document appears valid, 216 but the server is incapable of processing the request. There are 217 a number of situations that could lead to such a result, for 218 example: 219 * The client attempted to apply a patch document to an empty or 220 non-existent resource, but the patch document chosen cannot be 221 applied to an empty or non-existent resource. 223 * The client attempted to apply a structural modification and the 224 structures assumed to exist did not exist (e.g. a patch which 225 specifies changing element 'foo' to element 'bar' but element 226 'foo' doesn't exist). 227 * The client attempted to modify a resource in a way that would 228 cause the resource to become invalid. For instance, a 229 modification to a well-formed XML document that would cause it 230 to no longer be well-formed. 231 * The client attempted to modify a resource that has multiple 232 representations but the server was unable to choose which 233 representation to modify. 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. 271 Accept-Patch = "Accept-Patch" ":" ( "*" | #media-type ) 273 The Accept-Patch header specifies a comma separated listing of media- 274 types as defined by [RFC2616], Section 3.7. The asterisk character 275 "*" can be used to indicate that any patch format is accepted. 277 3.2. An example OPTIONS request and response 279 [request] 281 OPTIONS /example/buddies.xml HTTP/1.1 282 Host: www.example.com 284 [response] 286 HTTP/1.1 200 OK 287 Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH 288 Accept-Patch: application/example, text/example 290 The examples show a server that supports PATCH generally using two 291 hypothetical patch document formats. 293 4. 209 Content Returned 295 The 209 "Content Returned" status code can be used to indicate that a 296 response is equivalent to what would have been returned with a 200 297 status code response to a GET sent to the URI immediately following 298 the successful completion of the request. 300 5. IANA Considerations 302 5.1. The 'Accept-Patch' Response Header 304 The 'Accept-Patch' response header should be added to the permanent 305 registry (see [RFC3864]). 307 Header field name: Accept-Patch 308 Applicable Protocol: HTTP 309 Author/Change controller: IETF 310 Specification document: this specification 312 5.2. HTTP Status codes 314 This specification defines the 209 (Content Returned) status code 315 (Section 4) to be updated in the registry at 316 . 318 6. Security Considerations 320 The security considerations for PATCH are nearly identical to the 321 security considerations for PUT ([RFC2616], Section 9.6). These 322 include authorizing requests (possibly through access control and/or 323 authentication) and ensuring that data is not corrupted through 324 transport errors or through accidental overwrites. Whatever 325 mechanisms are used for PUT can be used for PATCH as well. The 326 following considerations apply specially to PATCH. 328 A document that is patched might be more likely to be corrupted than 329 a document that is overridden in entirety, but that concern can be 330 addressed through the use of mechanisms such as conditional requests 331 using ETags and the If-Match request header. 333 Sometimes an HTTP intermediary might try to detect viruses being sent 334 via HTTP by checking the body of the PUT/POST request or GET 335 response. The PATCH method complicates such watch-keeping because 336 neither the source document nor the patch document might be a virus, 337 yet the result could be. This security consideration is not 338 materially different from those already introduced by byte-range 339 downloads, downloading patch documents, uploading zipped (compressed) 340 files and so on. 342 Individual patch documents will have their own specific security 343 considerations that will likely vary depending on the types of 344 resources being patched. The considerations for patched binary 345 resources, for instance, will be different than those for patched XML 346 documents. 348 7. References 350 7.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 7.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 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 and Michael 377 Balloni 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 Appendix C. Notes to RFC Editor 541 The RFC Editor should remove this section and the Changes section. 543 Authors' Addresses 545 Lisa Dusseault 546 Messaging Architects 547 180 Peel Street, Suite 333 548 Montreal, QC H3C 2G7 549 Canada 551 Email: lisa.dusseault@messagingarchitects.com 553 James M. Snell 555 Email: jasnell@gmail.com 556 URI: http://www.snellspace.com