Individual Submission S. Potluri Internet-Draft J. Whitehead Expires: January 18, 2007 UC Santa Cruz July 17, 2006 New WebDAV Methods for Distributed Authoring - APPEND and PATCH draft-suma-append-patch-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 18, 2007. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document defines two new WebDAV methods - APPEND and PATCH - for distributed authoring. The methods defined in this specification will enable the DAV clients to transfer only the partial contents of a file when necessary instead of uploading the entire file via the PUT method. Potluri & Whitehead Expires January 18, 2007 [Page 1] Internet-Draft WebDAV Methods-Append/Patch July 2006 1. Introduction HTTP/WebDAV protocol defines the PUT method for authoring web resources. WebDAV clients can either create new resources or modify existing resources on the server using the PUT method. Most often WebDAV clients use the PUT method to modify a portion of the file/resource at the server. A disadvantage of the PUT method is that, the entire contents of the file/resource need to be uploaded when only a small part of the file has changed. For WebDAV clients using a wide-area connection, it is inefficient to transfer the entire file contents over the network when not required. The PATCH method defined in this specification provides an efficient way to transfer the modified contents of a file in one request, while the APPEND method provides a simple mechanism to append data to the end of a file/resource. Thus, these methods extend the WebDAV Distributed Authoring Protocol [1] and provide a mechanism for WebDAV clients to transfer partial contents of a resource when needed. 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [2]. 2. APPEND Method The APPEND method takes the content specified in the request body and appends it to the end of the resource identified by the Request-URI. DAV compliant resources MAY support the APPEND method. If the resource specified in the request header does not exist, APPEND method behaves like the PUT method and creates a new resource. 2.1. Status Codes 201 (Created) - A new resource was created. 204 (No content) - Appended the data in the request body successfully. 409 (Conflict) - A parent collection (ancestor) hasn't been created yet. 423 (Locked) - The resource is locked. 507 (Insufficient Storage) - The resource does not have sufficient Potluri & Whitehead Expires January 18, 2007 [Page 2] Internet-Draft WebDAV Methods-Append/Patch July 2006 space to record the state of the resource after the execution of this method. 2.2. Example - Append This example appends the text in the request body to the /~suma/ index.txt file on the server dav.cse.ucsc.edu. The file index.txt has the following contents. Hello World!!!! The following request is sent to the DAV server to append the text in the request body at the end of index.txt file. >>Request APPEND /~suma/index.txt HTTP/1.1 Host: dav.cse.ucsc.edu Content-type: text/plain Testing Append Hello World Again!!! >>Response HTTP/1.1 204 No Content The file index.txt after the data was appended to it. Hello World!!!! Testing Append Hello World Again!!! 3. PATCH Method The PATCH method takes the patch instructions specified in the request body and applies it to the resource identified by the Request-URI. DAV compliant resources MAY support the PATCH method. The Request header MUST specify the Patch-Type header and the request body MUST contain the patch instructions. 3.1. Patch-Type Header The Patch instructions contained in the request body describe how two files differ from each other. In other words, they contain the change commands that are to be applied to the file that requires the patch. The Patch-Type Header indicates the format of these patch Potluri & Whitehead Expires January 18, 2007 [Page 3] Internet-Draft WebDAV Methods-Append/Patch July 2006 instructions. The main goal behind the introduction of the new Patch-type header is extensibility. This header supports multiple patch instruction formats and enables the PATCH method to be applied to various different resource/file media types. The DAV server may have a list of Patch-Types which are mapped to the resource/file types. When the server receives a PATCH request it may verify that the Patch-Type corresponds to the resource type (by checking the getcontenttype property) and apply the patch instructions to the resource. DAV providers are free to define and implement different Patch-types that are suitable for the existing resource types. 3.2. Patch-Type - Normal A Patch-type of normal was defined to work with the resource-types of text/plain and text/plain and text/html. DAV providers that support the PATCH method MUST support the normal patch-type. The normal patch-type has a format that is very similar to the output from the unix diff utility[3]. A normal patch format contains a command followed by groups of lines that are different between two files. A change-command followed by a group looks like this: change-command < from-file-line < from-file-line.. --- > to-file-line > to-file-line.. The change-commands are of three types, each one consisting of a line number or a range of lines in the destination file, a character representing the type of change to make, and a line number or comma- separated range of lines in the source file. Here, the destination file is the file to which the patch is applied to, and the source file is the file that the destination file will look like after the patch has been applied. The change-commands for the normal patch format are as follows: lar - Adds the lines in range r of the source file after line l of the destination file. fct - Replaces the lines in range f of the destination file with lines in range t of the source file. rdl - Deletes the lines in range r from the destination file. Potluri & Whitehead Expires January 18, 2007 [Page 4] Internet-Draft WebDAV Methods-Append/Patch July 2006 The example discussed in the next section will further clarify the normal patch format. A DAV client could use the output of the unix diff utility for the patch instructions in the request body without understanding the normal patch format. 3.3. Example - Patch This example applies the Patch-text in the request body to blake.txt. The destination file blake.txt and the source file (will.txt) that blake.txt will represent after the PATCH method has been applied are shown below: blake.txt Golden Apollo, that thro' heaven wide Scatter'st the rays of light, and truth's beams Ah Sunflower, weary of time, Who countest the steps of the sun; Seeking after that sweet golden clime where the traveller's journey is done; Where the Youth pined away with desire, And the pale virgin shrouded in snow, will.txt Ah Sunflower, weary of time, Who countest the steps of the sun; Seeking after that sweet golden clime Where the traveller's journey is done; Where the Youth pined away with desire, And the pale virgin shrouded in snow, Arise from their graves, and aspire Where my Sunflower wishes to go! The PATCH method request/response is shown below. The Patch instructions in the request body contains three groups of change commands. The first command 1,2d0 deletes the first two lines in blake.txt. The second command 6c4,5 changes line 6 of blake.txt to read as lines 4-5 of will.txt. The third command 8a8,9 appends lines 8-9 of will.txt after line 8 of blake.txt. The end result of this PATCH method is that the file blake.txt looks like will.txt. Potluri & Whitehead Expires January 18, 2007 [Page 5] Internet-Draft WebDAV Methods-Append/Patch July 2006 >>Request PATCH /~suma/blake.txt HTTP/1.1 Host: dav.cse.ucsc.edu Content-type: text/plain Patch-type: normal 1,2d0 < Golden Apollo, that thro' heaven wide < Scatter'st the rays of light, and truth's beams 6c4,5 < where the traveller's journey is done; --- > Where the traveller's journey is done; > 8a8,9 > Arise from their graves, and aspire > Where my Sunflower wishes to go! >>Response HTTP/1.1 204 No Content 3.4. Status Codes 404 (Not Found) - The specified resource does not exist. 412 (Precondition Failed) - Patch-Type not compatible with the file type. 415 (Unsupported Media Type) - The server does not support the patch-type of the body. 403 (Forbidden) - Unsupported file type. 204 (No Content) - Successfully PATCHed. 422 (Unprocessable Entity) - Unsuccessful PATCH. 423 (Locked) - The specified resource is locked and the client either is not a lock owner or the lock type requires a lock token to be submitted and the client did not submit it. 507 (Insufficient Storage) - The server did not have sufficient space to apply the patch. Potluri & Whitehead Expires January 18, 2007 [Page 6] Internet-Draft WebDAV Methods-Append/Patch July 2006 4. IANA Considerations This document defines a new HTTP header - Patch-Type. IANA should add this to any HTTP header list that they maintain. Note to RFC Editor: this section may be removed on publication as an RFC. 5. Security Considerations This document does not introduce any additional security concerns. 6. Acknowledgments We would appreciate your comments on this document. Please send your comments to w3c-dist-auth@w3.org. 7. References 7.1. Normative References [1] Whitehead, E., Jensen, D., Carter, S., Goland, Y., and A. Faizi, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, February 1999. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 7.2. Informative References [3] Eggert, P., Berry, K., and L. Wall, "GNU Diffutils Manual - Comparing and Merging Files", May 2002. Potluri & Whitehead Expires January 18, 2007 [Page 7] Internet-Draft WebDAV Methods-Append/Patch July 2006 Authors' Addresses Suma Potluri University of California, Santa Cruz Dept. of Computer Science 1156 High Street Santa Cruz, CA 95064 Email: suma@cse.ucsc.edu Jim Whitehead University of California, Santa Cruz Dept. of Computer Science 1156 High Street Santa Cruz, CA 95064 Email: ejw@cse.ucsc.edu Potluri & Whitehead Expires January 18, 2007 [Page 8] Internet-Draft WebDAV Methods-Append/Patch July 2006 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Potluri & Whitehead Expires January 18, 2007 [Page 9]