5.5 DELETE

WebDAV clients use DELETE much more often than HTTP clients. DELETE is used to clean up temporary resources and remove resources that are no longer wanted. Since DELETE was defined in HTTP for any kind of resource, DELETE can be used to delete collections as well as ordinary resources (see Listing 5-4).

Listing 5-4 Successful DELETE collection.

Request:

 DELETE /users/alice/temp/ HTTP/1.1 Host: example.com  

Response:

 HTTP/1.0 204 No Content Date: Tue, 15 Nov 1994 08:12:31 GMT Content-Length: 0  

When resources are locked, the DELETE request must include the correct lock tokens to successfully delete the resources. If the DELETE request is successful, then all locks on deleted resources are removed. All properties are removed as well.

WebDAV introduces some new status codes that may be returned in response to a DELETE request: 102 Processing, 207 Multi-Status, 423 Locked, and 507 Insufficient Storage.

5.5.1 Multi-Status Response

A DELETE request to a WebDAV collection is automatically assumed to have a depth of infinity, even if a Depth header was not sent by the client. In fact, the depth must be infinity because if a collection is deleted, all its children must be deleted.

When multiple resources are addressed in a single DELETE request and there are internal failures, it becomes more difficult to report errors. The request to delete a number of resources could fail for a number of reasons the resources are locked or the user doesn't have permission and so on. WebDAV defines a special Multi-Status response body to hold as many error codes as necessary and a URL to associate with each error code so that the client can figure out which resources caused the request to fail. The client cannot assume that a 207 Multi-Status response is a success response. It is more frequently an error response, even though the response code is in the 200 block of codes.

Listing 5-5 is a failed attempt to delete a collection. The collection contained one locked child and one child that couldn't be deleted due to a permissions check failure.

Listing 5-5 DELETE collection with partial failure: Multi-Status response.

Request:

 DELETE /users/alice/temp/ HTTP/1.1 Host: www.example.com  

Response:

 HTTP/1.1 207 Multi-Status Content-Type: text/xml; charset=UTF-8 Content-Length: 230 Date: Wed, 12 Mar 2003 20:54:02 GMT <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:">    <D:response>       <D:href>http://www.example.com/users/alice/temp/           japan-trip-log.txt</D:href>       <D:status>HTTP/1.1 423 Locked</D:status>    </D:response>    <D:response>       <D:href>http://www.example.com/users/alice/temp/           meeting-notes.txt</D:href>       <D:status>HTTP/1.1 403 Forbidden</D:status>    </D:response> </D:multistatus> 

The 207 Multi-Status response body always begins with the top-level multistatus element. This element always contains one or more response elements. Each response element corresponds to a different resource for which status information is being provided. Each response element always contains an href element to identify the resource and a status element to explain what happened to it. The href element contains a URI with the address to the resource, and the status element contains an HTTP/1.1 status code and text, formatted together as a string.

URLs in Multi-Status

The response in Listing 5-5 includes the full URL for the resource to which the error applies. Although this may not be sufficiently clear in the original RFC2518 document, it is necessary to include the full URL for each errored resource inside a 207 Multi-Status response.

Successes in Multi-Status

The WebDAV specification says that success messages should not appear in the 207 Multi-Status response, on the theory that only errors need to be pointed out. In an atomic operation (such as PROPPATCH), there aren't supposed to be any successes if there are any failures. However, some server implementations include successes anyway, so the client must be prepared to ignore these. Some servers are known to return successes in 207 Multi-Status responses to MOVE requests. In fact, implementors increasingly recognize that success status codes are useful in Multi-Status responses, and the standard may change to reflect that.

Permissions Failures in Multi-Status

Permissions failures in 207 Multi-Status responses are a little peculiar because normally when a client receives a 401 Authorization Required response, the client prompts the user for authorization and repeats the entire request. However, when multiple operations are attempted, there may not be a single authorization (set of user permissions or credentials) that allows all operations to be accomplished. Therefore, the wisest thing for the client to do may be to retry the operations on the resources one by one, providing authorization as needed.

5.5.2 Handling XML Bodies

This is the first time I've shown an XML body as a request or response body. WebDAV uses XML to marshal large amounts of information in requests or responses. There are a couple tricky things to note.

Formatting of href Elements

The href element appears in many WebDAV XML bodies, but the Multi-Status response is the most common location. This element contains a text value that is a full URL. There are a couple of tricks to remember to handle this element correctly, because the set of valid URL characters is different from the set of valid XML characters, and invalid character escaping is different as well.

• URIs can legally contain the reserved character &, which must be escaped in XML. This character appears in HTTP URLs with parameters. If the & symbol appears in a URI within XML it must be escaped as & when marshaled in an XML element. WebDAV resource URLs don't often contain &, so this usually isn't an issue.

• URIs can't contain the characters < or >. Thus, there's no need to escape these characters so that the XML is valid. If by chance a WebDAV processor receives an href element with the characters &gt; or &lt;, then the URI in the element is not legal and this can be rejected as a bad request (or response).

• URIs can contain characters that are valid in XML but must be escaped for the URI itself to be legal. For example, a space frequently appears in file names, but it must be escaped as %20 in a URI. A sender must not put the unescaped space character in a href element, because space is illegal in URI. However, a WebDAV recipient seeing a href value with a space could choose to accept the value and escape it.

• Leading and trailing spaces should not appear. They can be stripped if received in an href element.

Formatting of status Elements

The status element also contains text, but it's much easier to handle because none of the status numbers or text used in HTTP or WebDAV contain <, >, or &. The only trick to remember is that servers might include extra spaces or line returns in this value, even though they shouldn't. A client can easily handle this by trimming beginning or trailing white space from the value before handling the value.

Don't Forget Prefixes

Listing 5-5 showed the D: prefix used to represent the DAV namespace. It's rather traditional to use a mnemonic to help the reader when XML is shown in books or specifications, so WebDAV examples frequently show D: or d:. However, the sender can declare any prefix. The sender could declare the DAV namespace to be the default namespace and have no prefix, or the sender could assign prefixes more randomly so that the DAV namespace is indicated with a prefix like b32:. Prefixes are case-sensitive.

Handling Extensions

WebDAV requires that clients and servers be able to handle unknown elements by ignoring them. For example, the Multi-Status response could be extended with a custom element, so that this fragment appears in a response like Listing 5-5:

 <D:response>    <D:href>http://www.example.com/users/alice/temp/         meeting-notes.txt</D:href>    <D:status>HTTP/1.1 403 Forbidden</D:status>    <e:status-explanation        xmlns:e="http://www.example.com/namespaces/">        You do not have permission to delete this resource.    </e:status-explanation> </D:response> 

WebDAV requires that this custom element be ignored if it is not understood by the client. This rule applies to all WebDAV XML body marshaling. "Ignored" means that the body is processed as if the unrecognized element were not there. It does not mean that the recipient ignores the body or throws an error.

5.5.3 Atomicity

WebDAV does not require the DELETE operation to be atomic. If errors occur during the deletion of a WebDAV collection, the server may behave in a number of ways.

A server could roll back the operation when errors occur, as Xythos WebFile Server does. This is guaranteed to leave the collection with a consistent set of resources in containers that still exist. When the failed DELETE is done, no resources have actually been removed. To remove resources, the client must either issue more granular DELETE requests or fix what when wrong and issue the collection DELETE request again.

A server could also offer best-effort DELETE, as IIS 5.0 does. Typically, in this case, the server starts trying to delete individual resources one by one. If a collection within the DELETE scope is empty, then the server attempts to delete the collection. Whenever the server encounters a failure, it continues deleting other resources, but it does not delete collections that still contain children. If a server does best-effort deleting, the WebDAV specification requires that it keep around parents of undeleted resources, so that clients can still address these resources and perhaps fix what went wrong. The client may then be able to finish the incomplete DELETE by issuing more DELETE requests.

A server could also quit working when it reaches the first failure, but this doesn't seem to be as useful to clients as either the atomic or the best-effort implementations. For one thing, that gives the client information about only one error, when there could be several undeletable resources. In any case, if a resource cannot be deleted, its parent must not be deleted. Therefore, if the resource /test/index.html cannot be deleted, then /test must not be deleted either.

With any of these variations, the server must still inform the client which resources could not be deleted by returning error codes in the Multi-Status response. However, it's still hard for the client to tell if the server did an atomic DELETE or a partial DELETE. That's because the RFC2518 specifically says that the DELETE Multi-Status response should not contain the 424 Failed Dependency status code. Thus, a server like Xythos WFS cannot report all the resources that could have been deleted but were not because the whole operation was rolled back. The response from IIS 5.0 is likely to be much the same it does not report all the resources that were successfully deleted. Both responses (atomic and partial failure) would look like Listing 5-5.

The client must issue a PROPFIND request following a failed collection DELETE request in order to see which resources remain.

5.5.4 Destroy Data or Move to Trash?

A successful DELETE can behave in a couple of different ways:

• It can remove the data that is referred to by the Request-URI.

• It can remove the mapping between the Request-URI and the data that is referred to. The data may still be somewhere on the repository for example, in a server-maintained "trash" or "recycling bin" collection.

The difference between these two behaviors depends on whether WebDAV methods operate on addresses (URLs) or on data (resources). This philosophical but sometimes practical debate has come up so many times, we'll explain the basic issues in the next section.

5.5.5 Operations on Addresses or Resources

There are a number of ways to think about operations when addresses are used as references for objects.

The first model is that operations apply to addresses. Under this model, when the client issues the DELETE request in Listing 5-4, the server unbinds or unmaps the address http:// www.example.com/users/alice/temp/ from any resource it is pointing to. After a successful DELETE, subsequent responses to that URL return 404 Not Found.

The other model is that operations apply to resources. When the client issues the DELETE request in Listing 5-4, the server locates the resource addressed by http://www.example.com/users/alice/temp/ and erases, removes, destroys, or deallocates the resource. After a successful DELETE, subsequent responses to that URL return 404 Not Found.

The client can't tell the difference between these cases, and WebDAV doesn't unambiguously require either behavior. The definition for DELETE on a noncollection in RFC2518 implies that the operation manipulates the address:

 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. 

However, the definition for DELETE on a collection resource implies that the operation acts on the underlying resource itself, rather than the address:

 DELETE instructs that the collection specified in the Request- URI and all resources identified by its internal member URIs are to be deleted. 

Most of the time, it doesn't matter to the client. Either way, the client sends a DELETE request to a URL, and subsequent requests to that URL return 404 Not Found. However, it matters greatly when writing a server implementation, because a clean addressing model helps a server implementor design clean interfaces and classes. It also matters to protocol designers considering extending WebDAV (see the sidebar, Addresses, Resources, and Bindings).

Since HTTP and WebDAV don't ever state firmly whether operations apply to addresses or data, various WebDAV extension designers and server implementors have made different unconscious or conscious assumptions. The lack of a firm model means that it's easier for servers to behave in whatever manner best suits their designs and purposes. On the other hand, it also means that clients and users can't know as much about what a server will really do. Just because a DELETE operation was successful, the user can't assume that the server has destroyed the data.

Addresses, Resources, and Bindings

The decision as to whether operations apply to addresses or resources is especially relevant to proposals to extend WebDAV to support bindings [Clemm03]. A server may have two addresses for the same collection of resources, or in other words, two bindings to the same collection resource. If a DELETE request is applied to one of those two bindings, one can imagine two results:

• The server applies the operation to the URL such that only that binding is destroyed, and the other binding continues to point to the same collection.

• The server applies the operation to the underlying collection such that the collection and its descendants are erased from storage. Either both bindings disappear or one disappears and the other breaks.

The bindings proposals will have to have a consistent approach and explain how it applies in many cases or define on a case-by-case basis what happens when multiple bindings exist.