RFC 2518
HTTP Extensions for Distributed Authoring -- WEBDAV
8 HTTP Methods for Distributed Authoring
The following new HTTP methods use XML as a request and response format. All DAV compliant clients and resources MUST use XML parsers that are compliant with [REC-XML]. All XML used in either requests or responses MUST be, at minimum, well formed. If a server receives
ill-formed XML in a request it MUST reject the entire request with a 400 (Bad Request). If a client receives ill-formed XML in a response then it MUST NOT assume anything about the outcome of the executed method and SHOULD treat the server as malfunctioning.8.1 PROPFIND
The PROPFIND method retrieves properties defined on the resource identified by the Request-URI, if the resource does not have any internal members, or on the resource identified by the Request-URI and potentially its member resources, if the resource is a collection that has internal member URIs. All DAV compliant resources MUST support the PROPFIND method and the propfind XML element (section 12.14) along with all XML elements defined for use with that element. A client may submit a Depth header with a value of "0", "1", or "infinity" with a PROPFIND on a collection resource with internal member URIs. DAV compliant servers MUST support the "0", "1" and "infinity" behaviors. By default, the PROPFIND method without a Depth header MUST act as if a "Depth: infinity" header was included. A client may submit a propfind XML element in the body of the request method describing what information is being requested. It is possible to request particular property values, all property values, or a list of the names of the resource's properties. A client may choose not to submit a request body. An empty PROPFIND request body MUST be treated as a request for the names and values of all properties. All servers MUST support returning a response of content type text/xml or application/xml that contains a multistatus XML element that describes the results of the attempts to retrieve the various properties. If there is an error retrieving a property then a proper error result MUST be included in the response. A request to retrieve the value of a property which does not exist is an error and MUST be noted, if the response uses a multistatus XML element, with a response XML element which contains a 404 (Not Found) status value. Consequently, the multistatus XML element for a collection resource with member URIs MUST include a response XML element for each member URI of the collection, to whatever depth was requested. Each response XML element MUST contain an href XML element that gives the URI of the resource on which the properties in the prop XML element are defined. Results for a PROPFIND on a collection resource with internal member URIs are returned as a flat list whose order of entries is not significant.
In the case of allprop and propname, if a principal does not have the right to know whether a particular property exists then the property should be silently excluded from the response. The results of this method SHOULD NOT be cached.8.1.1 Example - Retrieving Named Properties
>>Request PROPFIND /file HTTP/1.1 Host: www.foo.bar Content-type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox/> <R:author/> <R:DingALing/> <R:Random/> </D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.foo.bar/file</D:href> <D:propstat> <D:prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox> <R:BoxType>Box type A</R:BoxType> </R:bigbox> <R:author> <R:Name>J.J. Johnson</R:Name> </R:author> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> <D:propstat> <D:prop><R:DingALing/><R:Random/></D:prop>
<D:status>HTTP/1.1 403 Forbidden</D:status>
<D:responsedescription> The user does not have access to
the DingALing property.
</D:responsedescription>
</D:propstat>
</D:response>
<D:responsedescription> There has been an access violation error.
</D:responsedescription>
</D:multistatus>
In this example, PROPFIND is executed on a non-collection resource
http://www.foo.bar/file. The propfind XML element specifies the name
of four properties whose values are being requested. In this case
only two properties were returned, since the principal issuing the
request did not have sufficient access rights to see the third and
fourth properties.
8.1.2 Example - Using allprop to Retrieve All Properties
>>Request
PROPFIND /container/ HTTP/1.1
Host: www.foo.bar
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:allprop/>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foo.bar/container/</D:href>
<D:propstat>
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox>
<R:BoxType>Box type A</R:BoxType>
</R:bigbox>
<R:author>
<R:Name>Hadrian</R:Name>
</R:author>
<D:creationdate>
1997-12-01T17:42:21-08:00
</D:creationdate>
<D:displayname>
Example collection
</D:displayname>
<D:resourcetype><D:collection/></D:resourcetype>
<D:supportedlock>
<D:lockentry>
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
<D:lockentry>
<D:lockscope><D:shared/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
</D:supportedlock>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.foo.bar/container/front.html</D:href>
<D:propstat>
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox>
<R:BoxType>Box type B</R:BoxType>
</R:bigbox>
<D:creationdate>
1997-12-01T18:27:21-08:00
</D:creationdate>
<D:displayname>
Example HTML resource
</D:displayname>
<D:getcontentlength>
4525
</D:getcontentlength>
<D:getcontenttype>
text/html
</D:getcontenttype>
<D:getetag>
zzyzx
</D:getetag>
<D:getlastmodified>
Monday, 12-Jan-98 09:25:56 GMT
</D:getlastmodified>
<D:resourcetype/>
<D:supportedlock>
<D:lockentry>
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
<D:lockentry>
<D:lockscope><D:shared/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
</D:supportedlock>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
In this example, PROPFIND was invoked on the resource
http://www.foo.bar/container/ with a Depth header of 1, meaning the
request applies to the resource and its children, and a propfind XML
element containing the allprop XML element, meaning the request
should return the name and value of all properties defined on each
resource.
The resource http://www.foo.bar/container/ has six properties defined
on it:
http://www.foo.bar/boxschema/bigbox,
http://www.foo.bar/boxschema/author, DAV:creationdate,
DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
The last four properties are WebDAV-specific, defined in section 13.
Since GET is not supported on this resource, the get* properties
(e.g., getcontentlength) are not defined on this resource. The DAV-
specific properties assert that "container" was created on December
1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
(creationdate), has a name of "Example collection" (displayname), a
collection resource type (resourcetype), and supports exclusive write
and shared write locks (supportedlock).
The resource http://www.foo.bar/container/front.html has nine
properties defined on it:
http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
property type), DAV:creationdate, DAV:displayname,
DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
The DAV-specific properties assert that "front.html" was created on December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT (creationdate), has a name of "Example HTML resource" (displayname), a content length of 4525 bytes (getcontentlength), a MIME type of "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was last modified on Monday, January 12, 1998, at 09:25:56 GMT (getlastmodified), has an empty resource type, meaning that it is not a collection (resourcetype), and supports both exclusive write and shared write locks (supportedlock).8.1.3 Example - Using propname to Retrieve all Property Names
>>Request PROPFIND /container/ HTTP/1.1 Host: www.foo.bar Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <propfind xmlns="DAV:"> <propname/> </propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <multistatus xmlns="DAV:"> <response> <href>http://www.foo.bar/container/</href> <propstat> <prop xmlns:R="http://www.foo.bar/boxschema/"> <R:bigbox/> <R:author/> <creationdate/> <displayname/> <resourcetype/> <supportedlock/> </prop> <status>HTTP/1.1 200 OK</status> </propstat> </response> <response> <href>http://www.foo.bar/container/front.html</href>
<propstat>
<prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox/>
<creationdate/>
<displayname/>
<getcontentlength/>
<getcontenttype/>
<getetag/>
<getlastmodified/>
<resourcetype/>
<supportedlock/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
In this example, PROPFIND is invoked on the collection resource
http://www.foo.bar/container/, with a propfind XML element containing
the propname XML element, meaning the name of all properties should
be returned. Since no Depth header is present, it assumes its
default value of "infinity", meaning the name of the properties on
the collection and all its progeny should be returned.
Consistent with the previous example, resource
http://www.foo.bar/container/ has six properties defined on it,
http://www.foo.bar/boxschema/bigbox,
http://www.foo.bar/boxschema/author, DAV:creationdate,
DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
The resource http://www.foo.bar/container/index.html, a member of the
"container" collection, has nine properties defined on it,
http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
DAV:supportedlock.
This example also demonstrates the use of XML namespace scoping, and
the default namespace. Since the "xmlns" attribute does not contain
an explicit "shorthand name" (prefix) letter, the namespace applies
by default to all enclosed elements. Hence, all elements which do
not explicitly state the namespace to which they belong are members
of the "DAV:" namespace schema.
8.2 PROPPATCH
The PROPPATCH method processes instructions specified in the request body to set and/or remove properties defined on the resource identified by the Request-URI. All DAV compliant resources MUST support the PROPPATCH method and MUST process instructions that are specified using the propertyupdate, set, and remove XML elements of the DAV schema. Execution of the directives in this method is, of course, subject to access control constraints. DAV compliant resources SHOULD support the setting of arbitrary dead properties. The request message body of a PROPPATCH method MUST contain the propertyupdate XML element. Instruction processing MUST occur in the order instructions are received (i.e., from top to bottom). Instructions MUST either all be executed or none executed. Thus if any error occurs during processing all executed instructions MUST be undone and a proper error result returned. Instruction processing details can be found in the definition of the set and remove instructions in section 12.13.8.2.1 Status Codes for use with 207 (Multi-Status)
The following are examples of response codes one would expect to be used in a 207 (Multi-Status) response for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a 207 (Multi-Status) response. 200 (OK) - The command succeeded. As there can be a mixture of sets and removes in a body, a 201 (Created) seems inappropriate. 403 (Forbidden) - The client, for reasons the server chooses not to specify, cannot alter one of the properties. 409 (Conflict) - The client has provided a value whose semantics are not appropriate for the property. This includes trying to set read- only properties. 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 record the property.
8.2.2 Example - PROPPATCH
>>Request PROPPATCH /bar.html HTTP/1.1 Host: www.foo.com Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:propertyupdate xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50/"> <D:set> <D:prop> <Z:authors> <Z:Author>Jim Whitehead</Z:Author> <Z:Author>Roy Fielding</Z:Author> </Z:authors> </D:prop> </D:set> <D:remove> <D:prop><Z:Copyright-Owner/></D:prop> </D:remove> </D:propertyupdate> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:" xmlns:Z="http://www.w3.com/standards/z39.50"> <D:response> <D:href>http://www.foo.com/bar.html</D:href> <D:propstat> <D:prop><Z:Authors/></D:prop> <D:status>HTTP/1.1 424 Failed Dependency</D:status> </D:propstat> <D:propstat> <D:prop><Z:Copyright-Owner/></D:prop> <D:status>HTTP/1.1 409 Conflict</D:status> </D:propstat> <D:responsedescription> Copyright Owner can not be deleted or altered.</D:responsedescription> </D:response> </D:multistatus>
In this example, the client requests the server to set the value of the http://www.w3.com/standards/z39.50/Authors property, and to remove the property http://www.w3.com/standards/z39.50/Copyright- Owner. Since the Copyright-Owner property could not be removed, no property modifications occur. The 424 (Failed Dependency) status code for the Authors property indicates this action would have succeeded if it were not for the conflict with removing the Copyright-Owner property.8.3 MKCOL Method
The MKCOL method is used to create a new collection. All DAV compliant resources MUST support the MKCOL method.8.3.1 Request
MKCOL creates a new collection resource at the location specified by the Request-URI. If the resource identified by the Request-URI is non-null then the MKCOL MUST fail. During MKCOL processing, a server MUST make the Request-URI a member of its parent collection, unless the Request-URI is "/". If no such ancestor exists, the method MUST fail. When the MKCOL operation creates a new collection resource, all ancestors MUST already exist, or the method MUST fail with a 409 (Conflict) status code. For example, if a request to create collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists, the request must fail. When MKCOL is invoked without a request body, the newly created collection SHOULD have no members. A MKCOL request message may contain a message body. The behavior of a MKCOL request when the body is present is limited to creating collections, members of a collection, bodies of members and properties on the collections or members. If the server receives a MKCOL request entity type it does not support or understand it MUST respond with a 415 (Unsupported Media Type) status code. The exact behavior of MKCOL for various request media types is undefined in this document, and will be specified in separate documents.8.3.2 Status Codes
Responses from a MKCOL request MUST NOT be cached as MKCOL has non- idempotent semantics. 201 (Created) - The collection or structured resource was created in its entirety.
403 (Forbidden) - This indicates at least one of two conditions: 1) the server does not allow the creation of collections at the given location in its namespace, or 2) the parent collection of the Request-URI exists but cannot accept members. 405 (Method Not Allowed) - MKCOL can only be executed on a deleted/non-existent resource. 409 (Conflict) - A collection cannot be made at the Request-URI until one or more intermediate collections have been created. 415 (Unsupported Media Type)- The server does not support the request type of the body. 507 (Insufficient Storage) - The resource does not have sufficient space to record the state of the resource after the execution of this method.8.3.3 Example - MKCOL
This example creates a collection called /webdisc/xfiles/ on the server www.server.org. >>Request MKCOL /webdisc/xfiles/ HTTP/1.1 Host: www.server.org >>Response HTTP/1.1 201 Created8.4 GET, HEAD for Collections
The semantics of GET are unchanged when applied to a collection, since GET is defined as, "retrieve whatever information (in the form of an entity) is identified by the Request-URI" [RFC2068]. GET when applied to a collection may return the contents of an "index.html" resource, a human-readable view of the contents of the collection, or something else altogether. Hence it is possible that the result of a GET on a collection will bear no correlation to the membership of the collection. Similarly, since the definition of HEAD is a GET without a response message body, the semantics of HEAD are unmodified when applied to collection resources.
8.5 POST for Collections
Since by definition the actual function performed by POST is determined by the server and often depends on the particular resource, the behavior of POST when applied to collections cannot be meaningfully modified because it is largely undefined. Thus the semantics of POST are unmodified when applied to a collection.8.6 DELETE
8.6.1 DELETE for Non-Collection Resources
If the DELETE method is issued to a non-collection resource whose URIs are an internal member of one or more collections, then during DELETE processing a server MUST remove any URI for the resource identified by the Request-URI from collections which contain it as a member.8.6.2 DELETE for Collections
The DELETE method on a collection MUST act as if a "Depth: infinity" header was used on it. A client MUST NOT submit a Depth header with a DELETE on a collection with any value but infinity. DELETE instructs that the collection specified in the Request-URI and all resources identified by its internal member URIs are to be deleted. If any resource identified by a member URI cannot be deleted then all of the member's ancestors MUST NOT be deleted, so as to maintain namespace consistency. Any headers included with DELETE MUST be applied in processing every resource to be deleted. When the DELETE method has completed processing it MUST result in a consistent namespace. If an error occurs with a resource other than the resource identified in the Request-URI then the response MUST be a 207 (Multi-Status). 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi- Status). They can be safely left out because the client will know that the ancestors of a resource could not be deleted when the client receives an error for the ancestor's progeny. Additionally 204 (No Content) errors SHOULD NOT be returned in the 207 (Multi-Status). The reason for this prohibition is that 204 (No Content) is the default success code.
8.6.2.1 Example - DELETE
>>Request DELETE /container/ HTTP/1.1 Host: www.foo.bar >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:multistatus xmlns:d="DAV:"> <d:response> <d:href>http://www.foo.bar/container/resource3</d:href> <d:status>HTTP/1.1 423 Locked</d:status> </d:response> </d:multistatus> In this example the attempt to delete http://www.foo.bar/container/resource3 failed because it is locked, and no lock token was submitted with the request. Consequently, the attempt to delete http://www.foo.bar/container/ also failed. Thus the client knows that the attempt to delete http://www.foo.bar/container/ must have also failed since the parent can not be deleted unless its child has also been deleted. Even though a Depth header has not been included, a depth of infinity is assumed because the method is on a collection.8.7 PUT
8.7.1 PUT for Non-Collection Resources
A PUT performed on an existing resource replaces the GET response entity of the resource. Properties defined on the resource may be recomputed during PUT processing but are not otherwise affected. For example, if a server recognizes the content type of the request body, it may be able to automatically extract information that could be profitably exposed as properties. A PUT that would result in the creation of a resource without an appropriately scoped parent collection MUST fail with a 409 (Conflict).
8.7.2 PUT for Collections
As defined in the HTTP/1.1 specification [RFC2068], the "PUT method requests that the enclosed entity be stored under the supplied Request-URI." Since submission of an entity representing a collection would implicitly encode creation and deletion of resources, this specification intentionally does not define a transmission format for creating a collection using PUT. Instead, the MKCOL method is defined to create collections. When the PUT operation creates a new non-collection resource all ancestors MUST already exist. If all ancestors do not exist, the method MUST fail with a 409 (Conflict) status code. For example, if resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, then the request must fail.8.8 COPY Method
The COPY method creates a duplicate of the source resource, identified by the Request-URI, in the destination resource, identified by the URI in the Destination header. The Destination header MUST be present. The exact behavior of the COPY method depends on the type of the source resource. All WebDAV compliant resources MUST support the COPY method. However, support for the COPY method does not guarantee the ability to copy a resource. For example, separate programs may control resources on the same server. As a result, it may not be possible to copy a resource to a location that appears to be on the same server.8.8.1 COPY for HTTP/1.1 resources
When the source resource is not a collection the result of the COPY method is the creation of a new resource at the destination whose state and behavior match that of the source resource as closely as possible. After a successful COPY invocation, all properties on the source resource MUST be duplicated on the destination resource, subject to modifying headers and XML elements, following the definition for copying properties. Since the environment at the destination may be different than at the source due to factors outside the scope of control of the server, such as the absence of resources required for correct operation, it may not be possible to completely duplicate the behavior of the resource at the destination. Subsequent alterations to the destination resource will not modify the source resource. Subsequent alterations to the source resource will not modify the destination resource.
8.8.2. COPY for Properties
The following section defines how properties on a resource are handled during a COPY operation. Live properties SHOULD be duplicated as identically behaving live properties at the destination resource. If a property cannot be copied live, then its value MUST be duplicated, octet-for-octet, in an identically named, dead property on the destination resource subject to the effects of the propertybehavior XML element. The propertybehavior XML element can specify that properties are copied on best effort, that all live properties must be successfully copied or the method must fail, or that a specified list of live properties must be successfully copied or the method must fail. The propertybehavior XML element is defined in section 12.12.8.8.3 COPY for Collections
The COPY method on a collection without a Depth header MUST act as if a Depth header with value "infinity" was included. A client may submit a Depth header on a COPY on a collection with a value of "0" or "infinity". DAV compliant servers MUST support the "0" and "infinity" Depth header behaviors. A COPY of depth infinity instructs that the collection resource identified by the Request-URI is to be copied to the location identified by the URI in the Destination header, and all its internal member resources are to be copied to a location relative to it, recursively through all levels of the collection hierarchy. A COPY of "Depth: 0" only instructs that the collection and its properties but not resources identified by its internal member URIs, are to be copied. Any headers included with a COPY MUST be applied in processing every resource to be copied with the exception of the Destination header. The Destination header only specifies the destination URI for the Request-URI. When applied to members of the collection identified by the Request-URI the value of Destination is to be modified to reflect the current location in the hierarchy. So, if the Request- URI is /a/ with Host header value http://fun.com/ and the Destination is http://fun.com/b/ then when http://fun.com/a/c/d is processed it must use a Destination of http://fun.com/b/c/d.
When the COPY method has completed processing it MUST have created a consistent namespace at the destination (see section 5.1 for the definition of namespace consistency). However, if an error occurs while copying an internal collection, the server MUST NOT copy any resources identified by members of this collection (i.e., the server must skip this subtree), as this would create an inconsistent namespace. After detecting an error, the COPY operation SHOULD try to finish as much of the original copy operation as possible (i.e., the server should still attempt to copy other subtrees and their members, that are not descendents of an error-causing collection). So, for example, if an infinite depth copy operation is performed on collection /a/, which contains collections /a/b/ and /a/c/, and an error occurs copying /a/b/, an attempt should still be made to copy /a/c/. Similarly, after encountering an error copying a non- collection resource as part of an infinite depth copy, the server SHOULD try to finish as much of the original copy operation as possible. If an error in executing the COPY method occurs with a resource other than the resource identified in the Request-URI then the response MUST be a 207 (Multi-Status). The 424 (Failed Dependency) status code SHOULD NOT be returned in the 207 (Multi-Status) response from a COPY method. These responses can be safely omitted because the client will know that the progeny of a resource could not be copied when the client receives an error for the parent. Additionally 201 (Created)/204 (No Content) status codes SHOULD NOT be returned as values in 207 (Multi-Status) responses from COPY methods. They, too, can be safely omitted because they are the default success codes.8.8.4 COPY and the Overwrite Header
If a resource exists at the destination and the Overwrite header is "T" then prior to performing the copy the server MUST perform a DELETE with "Depth: infinity" on the destination resource. If the Overwrite header is set to "F" then the operation will fail.8.8.5 Status Codes
201 (Created) - The source resource was successfully copied. The copy operation resulted in the creation of a new resource. 204 (No Content) - The source resource was successfully copied to a pre-existing destination resource. 403 (Forbidden) _ The source and destination URIs are the same.
409 (Conflict) _ A resource cannot be created at the destination until one or more intermediate collections have been created. 412 (Precondition Failed) - The server was unable to maintain the liveness of the properties listed in the propertybehavior XML element or the Overwrite header is "F" and the state of the destination resource is non-null. 423 (Locked) - The destination resource was locked. 502 (Bad Gateway) - This may occur when the destination is on another server and the destination server refuses to accept the resource. 507 (Insufficient Storage) - The destination resource does not have sufficient space to record the state of the resource after the execution of this method.8.8.6 Example - COPY with Overwrite
This example shows resource http://www.ics.uci.edu/~fielding/index.html being copied to the location http://www.ics.uci.edu/users/f/fielding/index.html. The 204 (No Content) status code indicates the existing resource at the destination was overwritten. >>Request COPY /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html >>Response HTTP/1.1 204 No Content8.8.7 Example - COPY with No Overwrite
The following example shows the same copy operation being performed, but with the Overwrite header set to "F." A response of 412 (Precondition Failed) is returned because the destination resource has a non-null state. >>Request COPY /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html Overwrite: F
>>Response HTTP/1.1 412 Precondition Failed8.8.8 Example - COPY of a Collection
>>Request COPY /container/ HTTP/1.1 Host: www.foo.bar Destination: http://www.foo.bar/othercontainer/ Depth: infinity Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:propertybehavior xmlns:d="DAV:"> <d:keepalive>*</d:keepalive> </d:propertybehavior> >>Response HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <d:multistatus xmlns:d="DAV:"> <d:response> <d:href>http://www.foo.bar/othercontainer/R2/</d:href> <d:status>HTTP/1.1 412 Precondition Failed</d:status> </d:response> </d:multistatus> The Depth header is unnecessary as the default behavior of COPY on a collection is to act as if a "Depth: infinity" header had been submitted. In this example most of the resources, along with the collection, were copied successfully. However the collection R2 failed, most likely due to a problem with maintaining the liveness of properties (this is specified by the propertybehavior XML element). Because there was an error copying R2, none of R2's members were copied. However no errors were listed for those members due to the error minimization rules given in section 8.8.3.
8.9 MOVE Method
The MOVE operation on a non-collection resource is the logical equivalent of a copy (COPY), followed by consistency maintenance processing, followed by a delete of the source, where all three actions are performed atomically. The consistency maintenance step allows the server to perform updates caused by the move, such as updating all URIs other than the Request-URI which identify the source resource, to point to the new destination resource. Consequently, the Destination header MUST be present on all MOVE methods and MUST follow all COPY requirements for the COPY part of the MOVE method. All DAV compliant resources MUST support the MOVE method. However, support for the MOVE method does not guarantee the ability to move a resource to a particular destination. For example, separate programs may actually control different sets of resources on the same server. Therefore, it may not be possible to move a resource within a namespace that appears to belong to the same server. If a resource exists at the destination, the destination resource will be DELETEd as a side-effect of the MOVE operation, subject to the restrictions of the Overwrite header.8.9.1 MOVE for Properties
The behavior of properties on a MOVE, including the effects of the propertybehavior XML element, MUST be the same as specified in section 8.8.2.8.9.2 MOVE for Collections
A MOVE with "Depth: infinity" instructs that the collection identified by the Request-URI be moved to the URI specified in the Destination header, and all resources identified by its internal member URIs are to be moved to locations relative to it, recursively through all levels of the collection hierarchy. The MOVE method on a collection MUST act as if a "Depth: infinity" header was used on it. A client MUST NOT submit a Depth header on a MOVE on a collection with any value but "infinity". Any headers included with MOVE MUST be applied in processing every resource to be moved with the exception of the Destination header. The behavior of the Destination header is the same as given for COPY on collections.
When the MOVE method has completed processing it MUST have created a consistent namespace at both the source and destination (see section 5.1 for the definition of namespace consistency). However, if an error occurs while moving an internal collection, the server MUST NOT move any resources identified by members of the failed collection (i.e., the server must skip the error-causing subtree), as this would create an inconsistent namespace. In this case, after detecting the error, the move operation SHOULD try to finish as much of the original move as possible (i.e., the server should still attempt to move other subtrees and the resources identified by their members, that are not descendents of an error-causing collection). So, for example, if an infinite depth move is performed on collection /a/, which contains collections /a/b/ and /a/c/, and an error occurs moving /a/b/, an attempt should still be made to try moving /a/c/. Similarly, after encountering an error moving a non-collection resource as part of an infinite depth move, the server SHOULD try to finish as much of the original move operation as possible. If an error occurs with a resource other than the resource identified in the Request-URI then the response MUST be a 207 (Multi-Status). The 424 (Failed Dependency) status code SHOULD NOT be returned in the 207 (Multi-Status) response from a MOVE method. These errors can be safely omitted because the client will know that the progeny of a resource could not be moved when the client receives an error for the parent. Additionally 201 (Created)/204 (No Content) responses SHOULD NOT be returned as values in 207 (Multi-Status) responses from a MOVE. These responses can be safely omitted because they are the default success codes.8.9.3 MOVE and the Overwrite Header
If a resource exists at the destination and the Overwrite header is "T" then prior to performing the move the server MUST perform a DELETE with "Depth: infinity" on the destination resource. If the Overwrite header is set to "F" then the operation will fail.8.9.4 Status Codes
201 (Created) - The source resource was successfully moved, and a new resource was created at the destination. 204 (No Content) - The source resource was successfully moved to a pre-existing destination resource. 403 (Forbidden) _ The source and destination URIs are the same.
409 (Conflict) _ A resource cannot be created at the destination until one or more intermediate collections have been created. 412 (Precondition Failed) - The server was unable to maintain the liveness of the properties listed in the propertybehavior XML element or the Overwrite header is "F" and the state of the destination resource is non-null. 423 (Locked) - The source or the destination resource was locked. 502 (Bad Gateway) - This may occur when the destination is on another server and the destination server refuses to accept the resource.8.9.5 Example - MOVE of a Non-Collection
This example shows resource http://www.ics.uci.edu/~fielding/index.html being moved to the location http://www.ics.uci.edu/users/f/fielding/index.html. The contents of the destination resource would have been overwritten if the destination resource had been non-null. In this case, since there was nothing at the destination resource, the response code is 201 (Created). >>Request MOVE /~fielding/index.html HTTP/1.1 Host: www.ics.uci.edu Destination: http://www.ics.uci.edu/users/f/fielding/index.html >>Response HTTP/1.1 201 Created Location: http://www.ics.uci.edu/users/f/fielding/index.html8.9.6 Example - MOVE of a Collection
>>Request MOVE /container/ HTTP/1.1 Host: www.foo.bar Destination: http://www.foo.bar/othercontainer/ Overwrite: F If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) Content-Type: text/xml; charset="utf-8" Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:propertybehavior xmlns:d='DAV:'>
<d:keepalive>*</d:keepalive>
</d:propertybehavior>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:multistatus xmlns:d='DAV:'>
<d:response>
<d:href>http://www.foo.bar/othercontainer/C2/</d:href>
<d:status>HTTP/1.1 423 Locked</d:status>
</d:response>
</d:multistatus>
In this example the client has submitted a number of lock tokens with
the request. A lock token will need to be submitted for every
resource, both source and destination, anywhere in the scope of the
method, that is locked. In this case the proper lock token was not
submitted for the destination http://www.foo.bar/othercontainer/C2/.
This means that the resource /container/C2/ could not be moved.
Because there was an error copying /container/C2/, none of
/container/C2's members were copied. However no errors were listed
for those members due to the error minimization rules given in
section 8.8.3. User agent authentication has previously occurred via
a mechanism outside the scope of the HTTP protocol, in an underlying
transport layer.
8.10 LOCK Method
The following sections describe the LOCK method, which is used to
take out a lock of any access type. These sections on the LOCK
method describe only those semantics that are specific to the LOCK
method and are independent of the access type of the lock being
requested.
Any resource which supports the LOCK method MUST, at minimum, support
the XML request and response formats defined herein.
8.10.1 Operation
A LOCK method invocation creates the lock specified by the lockinfo XML element on the Request-URI. Lock method requests SHOULD have a XML request body which contains an owner XML element for this lock request, unless this is a refresh request. The LOCK request may have a Timeout header. Clients MUST assume that locks may arbitrarily disappear at any time, regardless of the value given in the Timeout header. The Timeout header only indicates the behavior of the server if "extraordinary" circumstances do not occur. For example, an administrator may remove a lock at any time or the system may crash in such a way that it loses the record of the lock's existence. The response MUST contain the value of the lockdiscovery property in a prop XML element. In order to indicate the lock token associated with a newly created lock, a Lock-Token response header MUST be included in the response for every successful LOCK request for a new lock. Note that the Lock-Token header would not be returned in the response for a successful refresh LOCK request because a new lock was not created.8.10.2 The Effect of Locks on Properties and Collections
The scope of a lock is the entire state of the resource, including its body and associated properties. As a result, a lock on a resource MUST also lock the resource's properties. For collections, a lock also affects the ability to add or remove members. The nature of the effect depends upon the type of access control involved.8.10.3 Locking Replicated Resources
A resource may be made available through more than one URI. However locks apply to resources, not URIs. Therefore a LOCK request on a resource MUST NOT succeed if can not be honored by all the URIs through which the resource is addressable.8.10.4 Depth and Locking
The Depth header may be used with the LOCK method. Values other than 0 or infinity MUST NOT be used with the Depth header on a LOCK method. All resources that support the LOCK method MUST support the Depth header. A Depth header of value 0 means to just lock the resource specified by the Request-URI.
If the Depth header is set to infinity then the resource specified in the Request-URI along with all its internal members, all the way down the hierarchy, are to be locked. A successful result MUST return a single lock token which represents all the resources that have been locked. If an UNLOCK is successfully executed on this token, all associated resources are unlocked. If the lock cannot be granted to all resources, a 409 (Conflict) status code MUST be returned with a response entity body containing a multistatus XML element describing which resource(s) prevented the lock from being granted. Hence, partial success is not an option. Either the entire hierarchy is locked or no resources are locked. If no Depth header is submitted on a LOCK request then the request MUST act as if a "Depth:infinity" had been submitted.8.10.5 Interaction with other Methods
The interaction of a LOCK with various methods is dependent upon the lock type. However, independent of lock type, a successful DELETE of a resource MUST cause all of its locks to be removed.8.10.6 Lock Compatibility Table
The table below describes the behavior that occurs when a lock request is made on a resource. Current lock state/ | Shared Lock | Exclusive Lock request | | Lock =====================+=================+============== None | True | True ---------------------+-----------------+-------------- Shared Lock | True | False ---------------------+-----------------+-------------- Exclusive Lock | False | False* ------------------------------------------------------ Legend: True = lock may be granted. False = lock MUST NOT be granted. *=It is illegal for a principal to request the same lock twice. The current lock state of a resource is given in the leftmost column, and lock requests are listed in the first row. The intersection of a row and column gives the result of a lock request. For example, if a shared lock is held on a resource, and an exclusive lock is requested, the table entry is "false", indicating the lock must not be granted.
8.10.7 Status Codes
200 (OK) - The lock request succeeded and the value of the lockdiscovery property is included in the body. 412 (Precondition Failed) - The included lock token was not enforceable on this resource or the server could not satisfy the request in the lockinfo XML element. 423 (Locked) - The resource is locked, so the method has been rejected.8.10.8 Example - Simple Lock Request
>>Request LOCK /workspace/webdav/proposal.doc HTTP/1.1 Host: webdav.sb.aol.com Timeout: Infinite, Second-4100000000 Content-Type: text/xml; charset="utf-8" Content-Length: xxxx Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." <?xml version="1.0" encoding="utf-8" ?> <D:lockinfo xmlns:D='DAV:'> <D:lockscope><D:exclusive/></D:lockscope> <D:locktype><D:write/></D:locktype> <D:owner> <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> </D:owner> </D:lockinfo> >>Response HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:prop xmlns:D="DAV:"> <D:lockdiscovery> <D:activelock> <D:locktype><D:write/></D:locktype> <D:lockscope><D:exclusive/></D:lockscope> <D:depth>Infinity</D:depth>
<D:owner>
<D:href>
http://www.ics.uci.edu/~ejw/contact.html
</D:href>
</D:owner>
<D:timeout>Second-604800</D:timeout>
<D:locktoken>
<D:href>
opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
</D:href>
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
This example shows the successful creation of an exclusive write lock
on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc.
The resource http://www.ics.uci.edu/~ejw/contact.html contains
contact information for the owner of the lock. The server has an
activity-based timeout policy in place on this resource, which causes
the lock to automatically be removed after 1 week (604800 seconds).
Note that the nonce, response, and opaque fields have not been
calculated in the Authorization request header.
8.10.9 Example - Refreshing a Write Lock
>>Request
LOCK /workspace/webdav/proposal.doc HTTP/1.1
Host: webdav.sb.aol.com
Timeout: Infinite, Second-4100000000
If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
Authorization: Digest username="ejw",
realm="ejw@webdav.sb.aol.com", nonce="...",
uri="/workspace/webdav/proposal.doc",
response="...", opaque="..."
>>Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:prop xmlns:D="DAV:">
<D:lockdiscovery>
<D:activelock>
<D:locktype><D:write/></D:locktype>
<D:lockscope><D:exclusive/></D:lockscope>
<D:depth>Infinity</D:depth>
<D:owner>
<D:href>
http://www.ics.uci.edu/~ejw/contact.html
</D:href>
</D:owner>
<D:timeout>Second-604800</D:timeout>
<D:locktoken>
<D:href>
opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
</D:href>
</D:locktoken>
</D:activelock>
</D:lockdiscovery>
</D:prop>
This request would refresh the lock, resetting any time outs. Notice
that the client asked for an infinite time out but the server choose
to ignore the request. In this example, the nonce, response, and
opaque fields have not been calculated in the Authorization request
header.
8.10.10 Example - Multi-Resource Lock Request
>>Request
LOCK /webdav/ HTTP/1.1
Host: webdav.sb.aol.com
Timeout: Infinite, Second-4100000000
Depth: infinity
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Authorization: Digest username="ejw",
realm="ejw@webdav.sb.aol.com", nonce="...",
uri="/workspace/webdav/proposal.doc",
response="...", opaque="..."
<?xml version="1.0" encoding="utf-8" ?>
<D:lockinfo xmlns:D="DAV:">
<D:locktype><D:write/></D:locktype>
<D:lockscope><D:exclusive/></D:lockscope>
<D:owner>
<D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
</D:owner>
</D:lockinfo>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://webdav.sb.aol.com/webdav/secret</D:href>
<D:status>HTTP/1.1 403 Forbidden</D:status>
</D:response>
<D:response>
<D:href>http://webdav.sb.aol.com/webdav/</D:href>
<D:propstat>
<D:prop><D:lockdiscovery/></D:prop>
<D:status>HTTP/1.1 424 Failed Dependency</D:status>
</D:propstat>
</D:response>
</D:multistatus>
This example shows a request for an exclusive write lock on a
collection and all its children. In this request, the client has
specified that it desires an infinite length lock, if available,
otherwise a timeout of 4.1 billion seconds, if available. The request
entity body contains the contact information for the principal taking
out the lock, in this case a web page URL.
The error is a 403 (Forbidden) response on the resource
http://webdav.sb.aol.com/webdav/secret. Because this resource could
not be locked, none of the resources were locked. Note also that the
lockdiscovery property for the Request-URI has been included as
required. In this example the lockdiscovery property is empty which
means that there are no outstanding locks on the resource.
In this example, the nonce, response, and opaque fields have not been
calculated in the Authorization request header.
8.11 UNLOCK Method
The UNLOCK method removes the lock identified by the lock token in
the Lock-Token request header from the Request-URI, and all other
resources included in the lock. If all resources which have been
locked under the submitted lock token can not be unlocked then the
UNLOCK request MUST fail.
Any DAV compliant resource which supports the LOCK method MUST
support the UNLOCK method.
8.11.1 Example - UNLOCK
>>Request UNLOCK /workspace/webdav/info.doc HTTP/1.1 Host: webdav.sb.aol.com Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> Authorization: Digest username="ejw", realm="ejw@webdav.sb.aol.com", nonce="...", uri="/workspace/webdav/proposal.doc", response="...", opaque="..." >>Response HTTP/1.1 204 No Content In this example, the lock identified by the lock token "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully removed from the resource http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock included more than just one resource, the lock is removed from all resources included in the lock. The 204 (No Content) status code is used instead of 200 (OK) because there is no response entity body. In this example, the nonce, response, and opaque fields have not been calculated in the Authorization request header.
(page 52 continued on part 3)
