The PROPFIND Method

The PROPFIND method retrieves the properties associated with a given resource or a collection. It can retrieve the names of all properties or all properties and their values or a subset of all the properties and their values.

Here is an example of a request retrieving all the properties:

PROPFIND http://localhost/digestdav/sample.txt HTTP/1.1
Host: localhost
User-Agent: cadaver/0.22.3 neon/0.25.5
Connection: TE
TE: trailers
Depth: 0
Content-Length: 86
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<propfind xmlns="DAV:">
  <allprop/>
</propfind>

The body of the PROPFIND request consists of an XML document, whose root is <propfind> and contains the node <allprop> as a single child. This means that all properties and their values will returned. The other alternatives for the child elements are <propname> which specifies the set of property names to be returned and < prop> which specifies a specific property whose value will be returned. If the PROPFIND request has no body, all properties are retrieved as if <allprop> was supplied.

Here is the response of the above request:

HTTP/1.1 207 Multi-Status
Date: Sun, 04 Jun 2006 00:55:58 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: 959
Content-Type: text/xml; charset="utf-8"

<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:ns0="DAV:">
  <D:response xmlns:lp1="DAV:"
      xmlns:lp3="http://subversion.tigris.org/xmlns/dav/"
      xmlns:lp2="http://apache.org/dav/props/">
    <D:href>/digestdav/sample.txt</D:href>
      <D:propstat>
      <D:prop>
        <lp1:resourcetype/>
        <lp1:creationdate>
          2006-05-19T07:04:45Z
        </lp1:creationdate>
        <lp1:getcontentlength>30</lp1:getcontentlength>
        <lp1:getlastmodified>
          Fri, 19 May 2006 07:04:45 GMT
        </lp1:getlastmodified>
        <lp1:getetag>"e82ce-1e-c47ddd40"</lp1:getetag>
        <lp2:executable>F</lp2:executable>
        <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:lockdiscovery/>
        <D:getcontenttype>text/plain</D:getcontenttype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

The status code of this response is 207 Multi-status, i.e. it is possible that the retrieving of the different properties resulted with different successes. For example if a set of properties are fetched successfully they will return a 200 OK response, but if another set of properties do not even exist a 404 Not Found response would be returned.

The root document of the response's body is < multistatus> which is a container for multiple responses. The element <href> specifies the URL whose properties are returned. The element < propstat> encapsulates one <prop> and one <status> element. The element < prop> contains one or more properties for the given resource; the element <status> contains the status code for the retrieval of those properties.

The properties retrieved in this case are:

resourcetype

Specifies the type of the resource. When the resource is a collection, it is set to collection, in other case it is empty;

creationdate

Contains the timestamp when the resource was created;

getcontentlength

Contains the Content-Length header that would be returned to a GET request for that resource;

getlastmodified

Contains the Last-Modified header that would be returned to a GET request for that resource;

getetag

Contains the ETag header that would be returned to a GET request for that resource;

executable

Specifies if the resource is executable;

supportedlock

Contains the lock capabilities supported by the resource;

lockdiscovery

Returns a listing of who has a lock, what type is that lock, when it is going to timeout and other information about the lock;

getcontenttype

Contains the Content-Type header that would be returned to a GET request for that resource.

It should be noted that the value of the property supportedlock is in XML format; when the value of a property is given in XML it must be well-formed.

This example shows only the properties managed by the server. The clients can also set their own properties using the PROPPATCH method.