Internet DRAFT - draft-suma-append-patch
draft-suma-append-patch
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]
