< draft-dusseault-http-patch-14.txt   draft-dusseault-http-patch-15.txt >
Network Working Group L. Dusseault Network Working Group L. Dusseault
Internet-Draft Messaging Architects Internet-Draft Linden Lab
Intended status: Standards Track J. Snell Intended status: Standards Track J. Snell
Expires: October 15, 2009 April 13, 2009 Expires: April 18, 2010 October 15, 2009
PATCH Method for HTTP PATCH Method for HTTP
draft-dusseault-http-patch-14 draft-dusseault-http-patch-15
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 32 skipping to change at page 1, line 32
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on October 15, 2009. This Internet-Draft will expire on April 18, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 15 skipping to change at page 2, line 15
This proposal adds a new HTTP method, PATCH, to modify an existing This proposal adds a new HTTP method, PATCH, to modify an existing
HTTP resource. HTTP resource.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. The PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3 2. The PATCH Method . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. A simple PATCH example . . . . . . . . . . . . . . . . . . 5 2.1. A simple PATCH example . . . . . . . . . . . . . . . . . . 5
2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Error handling . . . . . . . . . . . . . . . . . . . . . . 5
3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6 3. Advertising Support in OPTIONS . . . . . . . . . . . . . . . . 6
3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 6 3.1. The Accept-Patch Header . . . . . . . . . . . . . . . . . 7
3.2. Example OPTIONS Request and Response . . . . . . . . . . . 7 3.2. Example OPTIONS Request and Response . . . . . . . . . . . 7
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
4.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 7 4.1. The 'Accept-Patch' Response Header . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8
6.2. Informative References . . . . . . . . . . . . . . . . . . 8 6.2. Informative References . . . . . . . . . . . . . . . . . . 9
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9
Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9 Appendix B. Changes . . . . . . . . . . . . . . . . . . . . . . . 9
B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9 B.1. Changes from -00 . . . . . . . . . . . . . . . . . . . . . 9
B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9 B.2. Changes from -01 . . . . . . . . . . . . . . . . . . . . . 9
B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 9 B.3. Changes from -02 . . . . . . . . . . . . . . . . . . . . . 9
B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10 B.4. Changes from -03 . . . . . . . . . . . . . . . . . . . . . 10
B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10 B.5. Changes from -04 . . . . . . . . . . . . . . . . . . . . . 10
B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10 B.6. Changes from -05 . . . . . . . . . . . . . . . . . . . . . 10
B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 10 B.7. Changes from -06 . . . . . . . . . . . . . . . . . . . . . 10
B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11 B.8. Changes from -07 . . . . . . . . . . . . . . . . . . . . . 11
B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11 B.9. Changes from -08 . . . . . . . . . . . . . . . . . . . . . 11
B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 11 B.10. Changes from -09 . . . . . . . . . . . . . . . . . . . . . 12
B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 12 B.11. Changes from -10 . . . . . . . . . . . . . . . . . . . . . 12
B.12. Changes from -11 . . . . . . . . . . . . . . . . . . . . . 12 B.12. Changes from -11 . . . . . . . . . . . . . . . . . . . . . 12
B.13. Changes from -12 . . . . . . . . . . . . . . . . . . . . . 12 B.13. Changes from -12 . . . . . . . . . . . . . . . . . . . . . 12
B.14. Changes from -13 . . . . . . . . . . . . . . . . . . . . . 12 B.14. Changes from -13 . . . . . . . . . . . . . . . . . . . . . 12
B.15. Changes from -14 . . . . . . . . . . . . . . . . . . . . . 13
Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 13 Appendix C. Notes to RFC Editor . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
This specification defines the new HTTP/1.1 [RFC2616] method PATCH This specification defines the new HTTP/1.1 [RFC2616] method PATCH
that is used to apply partial modifications to a resource. that is used to apply partial modifications to a resource.
A new method is necessary to improve interoperability and prevent A new method is necessary to improve interoperability and prevent
errors. The PUT method is already defined to overwrite a resource errors. The PUT method is already defined to overwrite a resource
with a complete new body, and can not be reused to do partial with a complete new body, and can not be reused to do partial
changes. Otherwise, proxies and caches and even clients and servers changes. Otherwise, proxies and caches and even clients and servers
may get confused as to the result of the operation. may get confused as to the result of the operation. PATCH was
mentioned in earlier HTTP specifications, but not completely defined.
In this document, the key words "MUST", "MUST NOT", "REQUIRED", In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in [RFC2119]. and "OPTIONAL" are to be interpreted as described in [RFC2119].
Furthermore, this document uses the ABNF syntax defined in Section Furthermore, this document uses the ABNF syntax defined in Section
2.1 of [RFC2616]. 2.1 of [RFC2616].
2. The PATCH Method 2. The PATCH Method
skipping to change at page 3, line 46 skipping to change at page 3, line 47
The difference between the PUT and PATCH requests is reflected in the The difference between the PUT and PATCH requests is reflected in the
way the server processes the enclosed entity to modify the resource way the server processes the enclosed entity to modify the resource
identified by the Request-URI. In a PUT request, the enclosed entity identified by the Request-URI. In a PUT request, the enclosed entity
is considered to be a modified version of the resource stored on the is considered to be a modified version of the resource stored on the
origin server and the client is requesting that the stored version be origin server and the client is requesting that the stored version be
replaced. With PATCH, however, the enclosed entity contains a set of replaced. With PATCH, however, the enclosed entity contains a set of
instructions describing how a resource currently residing on the instructions describing how a resource currently residing on the
origin server should be modified to produce a new version. The PATCH origin server should be modified to produce a new version. The PATCH
method affects the resource identified by the Request-URI, and also method affects the resource identified by the Request-URI, and also
MAY have side effects on other resources; i.e., new resources may be MAY have side effects on other resources; i.e., new resources may be
created, or existing ones modified, by the application of a PATCH created, or existing ones modified, by the application of a PATCH.
(again, depending on the patch document type).
The server MUST apply the entire set of changes atomically and never The server MUST apply the entire set of changes atomically and never
provide (e.g. in response to a GET during this operation) a provide (e.g. in response to a GET during this operation) a
partially-modified representation. If the entire patch document partially-modified representation. If the entire patch document
cannot be successfully applied then the server MUST fail the entire cannot be successfully applied then the server MUST fail the entire
request, applying none of the changes. The determination of what request, applying none of the changes. The determination of what
constitutes a successful PATCH can vary depending on the patch constitutes a successful PATCH can vary depending on the patch
document and the type of resource being modified. See Error Handling document and the type of resource being modified. See Error Handling
in Section 2.2 for details on status codes and possible error in Section 2.2 for details on status codes and possible error
conditions. conditions.
If the request passes through a cache and the Request-URI identifies If the request passes through a cache and the Request-URI identifies
one or more currently cached entities, those entries SHOULD be one or more currently cached entities, those entries SHOULD be
treated as stale. Responses to this method are only cacheable if the treated as stale. A response to this method is only cacheable if it
server indicates, and if the cacheable resource is indicated with the contains explicit freshness information (such as an Expires header or
Content-Location header. "Cache-Control: max-age" directive) as well as the Content-Location
header matching the request-URI, indicating that the PATCH response
body is a resource representation. A cached PATCH response can only
be used to respond to subsequent GET and HEAD requests; it MUST NOT
be used to respond to other methods (in particular, PATCH).
Collisions from multiple PATCH requests are more dangerous than PUT Collisions from multiple PATCH requests are more dangerous than PUT
collisions, because a patch document that is not operating from a collisions, because a patch document that is not operating from a
known base point may corrupt the resource. Clients wishing to apply known base point may corrupt the resource. Clients wishing to apply
a patch document to a known entity can first acquire the strong ETag a patch document to a known entity can first acquire the strong ETag
of the resource to be modified, and use that Etag in the If-Match [RFC2616] of the resource to be modified, and use that Etag in the
header on the PATCH request to verify that the resource is still If-Match header on the PATCH request to verify that the resource is
unchanged. If a strong ETag is not available for a given resource, still unchanged. If a strong ETag is not available for a given
the client can use If-Unmodified-Since as a less-reliable safeguard. resource, the client can use If-Unmodified-Since as a less-reliable
safeguard.
Note that entity-headers contained in the request apply only to the Note that entity-headers contained in the request apply only to the
contained patch document and MUST NOT be applied to the resource contained patch document and MUST NOT be applied to the resource
being modified. Thus, a Content-Language header could be present on being modified. Thus, a Content-Language header could be present on
the request but it would only mean (for whatever that's worth) that the request but it would only mean (for whatever that's worth) that
the patch document had a language. Servers SHOULD NOT store such the patch document had a language. Servers SHOULD NOT store such
headers except as trace information, and SHOULD NOT use such header headers except as trace information, and SHOULD NOT use such header
values the same way they might be used on PUT requests. Therefore, values the same way they might be used on PUT requests. Therefore,
this document does not specify a way to modify a document's Content- this document does not specify a way to modify a document's Content-
Type or Content-Language value through headers, though a mechanism Type or Content-Language value through headers, though a mechanism
skipping to change at page 5, line 19 skipping to change at page 5, line 24
PATCH /file.txt HTTP/1.1 PATCH /file.txt HTTP/1.1
Host: www.example.com Host: www.example.com
Content-Type: application/example Content-Type: application/example
If-Match: "e0023aa4e" If-Match: "e0023aa4e"
Content-Length: 100 Content-Length: 100
[description of changes] [description of changes]
This example illustrates use of a hypothetical patch document on an This example illustrates use of a hypothetical patch document on an
existing resource. existing resource. The 204 response code is used because the
response does not have a body (a response with the 200 code would
have a body) but other success codes MAY be used if appropriate.
Successful PATCH response to existing text file Successful PATCH response to existing text file
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
ETag: "e0023aa4f" ETag: "e0023aa4f"
2.2. Error handling 2.2. Error handling
There are several known conditions under which a PATCH request can There are several known conditions under which a PATCH request can
fail. fail.
skipping to change at page 6, line 49 skipping to change at page 7, line 10
A server can advertise its support for the PATCH method by adding it A server can advertise its support for the PATCH method by adding it
to the listing of allowed methods in the "Allow" OPTIONS response to the listing of allowed methods in the "Allow" OPTIONS response
header defined in HTTP/1.1. The PATCH method MAY appear in the header defined in HTTP/1.1. The PATCH method MAY appear in the
"Allow" header even if the Accept-Patch header is absent, in which "Allow" header even if the Accept-Patch header is absent, in which
case the list of allowed patch documents is not advertised. case the list of allowed patch documents is not advertised.
3.1. The Accept-Patch Header 3.1. The Accept-Patch Header
This specification introduces a new response header "Accept-Patch" This specification introduces a new response header "Accept-Patch"
used to specify the patch document formats accepted by the server. used to specify the patch document formats accepted by the server.
"Accept-Patch" MUST appear in the OPTIONS response for any resource "Accept-Patch" SHOULD appear in the OPTIONS response for any resource
that supports the use of the PATCH method. The presence of the that supports the use of the PATCH method. The presence of the
"Accept-Patch" header in response to any method is an implicit "Accept-Patch" header in response to any method is an implicit
indication that PATCH is allowed on the resource identified by the indication that PATCH is allowed on the resource identified by the
Request-URI. The presence of a specific patch document format in Request-URI. The presence of a specific patch document format in
this header indicates that specific format is allowed on the resource this header indicates that specific format is allowed on the resource
identified by the Request-URI. identified by the Request-URI.
Accept-Patch = "Accept-Patch" ":" 1#media-type Accept-Patch = "Accept-Patch" ":" 1#media-type
The Accept-Patch header specifies a comma separated listing of media- The Accept-Patch header specifies a comma separated listing of media-
skipping to change at page 13, line 5 skipping to change at page 13, line 11
B.14. Changes from -13 B.14. Changes from -13
Remove '*' value from Accept-Patch again. Remove '*' value from Accept-Patch again.
Allow caching but only if context is clear. Allow caching but only if context is clear.
Clarify how some patch formats might allow creating a new document. Clarify how some patch formats might allow creating a new document.
Add comparison of PATCH to POST Add comparison of PATCH to POST
B.15. Changes from -14
Clarified that Accept-Patch header SHOULD appear in OPTIONS response
-- it is not absolutely required
Clarified how server can indicate that a PATCH response body is
cachable as a resource representation.
Removed suggestion that PATCH side-effects might be specified in the
patch document specification -- this implied that side-effects could
exclusively be determined that way, but in fact side-effects are
often determined by the server unilaterally.
Appendix C. Notes to RFC Editor Appendix C. Notes to RFC Editor
The RFC Editor should remove this section and the Changes section. The RFC Editor should remove this section and the Changes section.
Authors' Addresses Authors' Addresses
Lisa Dusseault Lisa Dusseault
Messaging Architects Linden Lab
180 Peel Street, Suite 333 945 Battery Street
Montreal, QC H3C 2G7 San Francisco, CA 94111
Canada USA
Email: lisa.dusseault@messagingarchitects.com Email: lisa.dusseault@gmail.com
James M. Snell James M. Snell
Email: jasnell@gmail.com Email: jasnell@gmail.com
URI: http://www.snellspace.com URI: http://www.snellspace.com
 End of changes. 18 change blocks. 
25 lines changed or deleted 46 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/