7.3 PROPPATCH

PROPPATCH requires a new kind of request syntax to change properties and property values. Clients need to be able to set values and remove a number of properties in the same request. However, only one resource can be addressed in a PROPPATCH request (the Depth header is not supported).

7.3.1 PROPPATCH Request

WebDAV marshals the PROPPATCH request information in an XML body with set and remove elements to change or create properties and remove them. Multiple prop elements can appear inside the set and remove elements, but Listing 7-10 just shows one of each.

Listing 7-10 PROPPATCH request.

 PROPPATCH /hr/ergonomics/chairs.doc HTTP/1.1 Host: www.example.com Content-Type: text/xml Content-Length: xxx  <?xml version="1.0" encoding="utf-8" ?> <propertyupdate xmlns='DAV:'    xmlns:X="http://www.example.com">    <set><prop><X:publish>true</X:publish></prop></set>    <remove><prop><X:temp-property/></prop></remove> </propertyupdate> 

In Listing 7-10, the client is asking the server to set the value of the publish property in the http://www.example.com namespace to true. If the property didn't exist already, it should be created. The client also wants temp-property in the same namespace to be removed. Note that it's necessary to have a syntax to remove elements, because an empty property is not the same as a property that's not there. Thus, it wouldn't be sufficient for the client to set the value of the property to an empty string.

The remove element contains only property names, not property values; the property name element must be empty. Note that if the property to be removed does not exist, the server must not return an error.

7.3.2 Implementing Atomic Requests

WebDAV defines the PROPPATCH operation to be atomic; all the property changes must be made together or not at all. Not all servers support atomic PROPPATCH, unfortunately. Instead, IIS 5.0 does best-effort PROPPATCH, where some properties may be changed and others unaltered. Servers are not normally supposed to use success responses within Multi-Status response bodies, but IIS does, since it may successfully change some properties but not others and the client needs to know which.

Despite recurring discussion about this requirement of WebDAV, there is no clear and satisfactory solution. The original intent of defining PROPPATCH as atomic was that it was assumed that resources would have multiple dependent properties. For example, the client might want to set publish to true only if draft can be set to false.

Some argued to abolish the atomicity requirement with the assumption that clients more frequently want to have best-effort property changes applied. However, that's not a good reason to change the atomicity requirement, because clients have another way to do best-effort property changes without incurring multiple roundtrips: by pipelining multiple PROPPATCH requests, each with one property set request.

A somewhat stronger argument against atomicity might be derived from a pragmatic look at implementation experience. It can be a little difficult for servers to implement atomic PROPPATCH. Atomic operations can require transaction capability, so that the server can roll back property changes that have already been made when a later part of the request fails. However, mod_dav supports atomicity even though it's based on a nontransacted file system. Servers that are based on transacted database storage, like Zope and Xythos WebFile Server, do, of course, implement atomic PROPPATCH.

Given that most servers do support atomic PROPPATCH, modern WebDAV clients that respect the standard will probably have an expectation that a failure means no changes were made. If some properties were changed and others were not, the client might experience a number of caching and resource integrity problems based on mismatched expectations.

7.3.3 PROPPATCH Response

A successful PROPPATCH response must have all properties changed successfully, but normally a Multi-Status is used anyway. This could allow properties that already existed and are being modified to report back a 200 OK, while properties that are being newly created could report back a 201 Created. It seems, however, that most servers simply report 200 OK for every property that was changed (removed or set), regardless of whether the property existed before.

A PROPPATCH response is a slight simplification of the PROPFIND response because it can only contain one response element. That may contain a number of propstat elements, depending on how many properties were manipulated. The values are never included, just the property names and namespaces.

Listing 7-11 is what a successful response to the request in Listing 7-10 might look like.

Listing 7-11 PROPPATCH response.

 HTTP/1.0 207 MultiPart Response Date: Sun, 29 Jul 2001 15:24:17 GMT Content-Type: text/xml; charset=UTF-8 Content-Length: xxx  <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"    xmlns:ns1="http://www.example.com"> <D:response>    <D:href>http://www.example.com/hr/drafts/chairs.doc</D:href>    <D:propstat>       <D:prop><ns1:publish/></D:prop>       <D:status>HTTP/1.1 200 OK</D:status>    </D:propstat>    <D:propstat>       <D:prop><ns1:temp-property/></D:prop>       <D:status>HTTP/1.1 200 OK</D:status>    </D:propstat> </D:response> </D:multistatus> 

7.3.4 PROPPATCH Response with Failures

When the PROPPATCH request fails, any property that could not be set is returned in the body with an appropriate error code such as 403 Forbidden. Any property that could have been set but was not because the request must be done atomically is returned with a status of 424 Failed Dependency.

Recall that the request in Section 7.3.1 attempted to set the value of the publish property and to remove the temp-property property. Since PROPPATCH is atomic, if either of those operations fail, both must fail. To illustrate this, imagine that the set request for publish fails because the property value was rejected by the server. There's no reason to fail to remove the temp-property property other than the failure to set publish, so the appropriate status code for temp-property is 424 Failed Dependency (see Listing 7-12).

Listing 7-12 PROPPATCH response body with failed dependencies.

 <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"    xmlns:ns1="http://www.example.com"> <D:response>    <D:href>http://www.example.com/hr/drafts/chairs.doc    </D:href>    <D:propstat>       <D:prop><ns1:publish/></D:prop>       <D:status>HTTP/1.1 409 Conflict</D:status>    </D:propstat>    <D:propstat>       <D:prop><ns1:temp-property/></D:prop>       <D:status>HTTP/1.1 424 Failed Dependency</D:status>    </D:propstat> </D:response> </D:multistatus> 

7.3.5 PROPPATCH to Nonexistent Resource

The WebDAV specification doesn't explicitly state what to do with a PROPPATCH request when the resource doesn't exist. We can imagine two possibilities: either the server returns 404 Not Found, or it creates a new resource and returns 201 Created. Most servers do the former. The specification writers intended PROPPATCH to fail when the resource doesn't exist, because all the methods that are intended to create new resources are carefully documented to explain that behavior and how it must work, but PROPPATCH does not include this kind of documentation.

Microsoft Exchange 2000 will allow PROPPATCH of a null resource to create a regular resource that cannot be made a collection. This is nonstandard behavior, although it doesn't seem to be particularly harmful.