The PUT Method

The PUT method is not defined by WebDAV; it is defined by the HTTP specification to store the entity given in its body as a resource on the server. On the other hand, WebDAV introduces the notion of collections which are resources that can contain other resources and the notion of member resources, which do not contain other resources. If PUT method were extended to support collection uploading, its body would contain instruction to delete and create resources, which would overly-complicate it. It would also make administering an HTTP server more difficult since restrictions on it are made on per-method basis. These are the reason why PUT method is extended by WebDAV only to support resources locks and not collection uploading.

Here is a simple PUT request sent to a non-locked collection:

PUT http://localhost/digestdav/sample.txt HTTP/1.1
Host: localhost
User-Agent: cadaver/0.22.3 neon/0.25.5
Connection: TE
TE: trailers
Content-Length: 68

This is the content of the file that will
be uploaded to the server

The body of the method contains the entity that will be upload to the specified resource. If the resource did not exist on the server, the response will be 201 Created:

HTTP/1.1 201 Created
Date: Sat, 10 Jun 2006 04:27:00 GMT
Server: Apache/2.2.2 (FreeBSD) mod_ssl/2.2.2 OpenSSL/0.9.7e-p1
  DAV/2 SVN/1.3.1 mod_jk/1.2.15
Location: http://localhost/digestdav/sample.txt
Content-Length: 193
Content-Type: text/html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>201 Created</title>
</head><body>
<h1>Created</h1>
<p>Resource /digestdav/sample.txt has been created.</p>
</body></html>

If the resource already existed on the server, that the entity replaces the previous content and the response is 204 No Content:

HTTP/1.1 204 No Content
Date: Sat, 10 Jun 2006 04:42:52 GMT
Server: Apache/2.2.2 (FreeBSD) mod_ssl/2.2.2 OpenSSL/0.9.7e-p1
  DAV/2 SVN/1.3.1 mod_jk/1.2.15
Content-Length: 0
Content-Type: text/plain

In the case when the resource is newly created its exact URL is given in the Location header of the response; this header is not set when the resource existed before.

Now if the resource or the collection containing the resource is locked the client must provide an opaque locktoken in the If header:

PUT http://localhost/digestdav/sample.txt HTTP/1.1
Host: localhost
User-Agent: cadaver/0.22.3 neon/0.25.5
Connection: TE
TE: trailers
Content-Length: 94
If: <http://localhost/digestdav/sample.txt> 
  (<opaquelocktoken:930a70c3-3df8-da11-a875-00c09fda2406>)
Authorization: Digest username="admin",
  realm="WebDAV Repository",
  nonce="BzUnkdcVBAA=fc5613be4bfb1040c1aed157a4f74866e1b2fc13",
  uri="http://localhost/digestdav/sample.txt",
  response="644ceb13496ea0d76aec5ed2a034ac98",
  algorithm="MD5",
  cnonce="59c1f7e0157ae31885626fe8cde65b11",
  nc=00000005, qop="auth"

This is the new content of the file that will
be uploaded to the server to a locked resource.

If the opaque locktoken matches than a successful 200 or 204 response is return. If the client does not provide a locktoken or it is does not matches, this means that the client does not posses the lock for the resource and a 423 Locked response is returned:

HTTP/1.1 423 Locked
Date: Sat, 10 Jun 2006 05:15:37 GMT
Server: Apache/2.2.2 (FreeBSD) mod_ssl/2.2.2
  OpenSSL/0.9.7e-p1 DAV/2 SVN/1.3.1 mod_jk/1.2.15
Content-Length: 277
Content-Type: text/html; charset=iso-8859-1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>423 Locked</title>
</head><body>
<h1>Locked</h1>
<p>The requested resource is currently locked.
The lock must be released or proper identification
given before the method can be applied.</p>
</body></html>

Иван Иванов 2006-06-23