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 URLs. All DAV-compliant resources MUST support the PROPFIND method and the propfind XML element (Section 14.20) along with all XML elements defined for use with that element.

A client MUST submit a Depth header with a value of "0", "1", or "infinity" with a PROPFIND request. Servers MUST support "0" and "1" depth requests on WebDAV-compliant resources and SHOULD support "infinity" requests. In practice, support for infinite-depth requests MAY be disabled, due to the performance and security concerns associated with this behavior. Servers SHOULD treat a request without a Depth header 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, by naming the properties desired within the prop element (the ordering of properties in here MAY be ignored by the server),
• Request property values for those properties defined in this specification (at a minimum) plus dead properties, by using the allprop element (the include element can be used with allprop to instruct the server to also include additional live properties that may not have been returned otherwise),
• Request a list of names of all the properties defined on the resource, by using the propname element.

A client may choose not to submit a request body. An empty PROPFIND request body MUST be treated as if it were an allprop request.

Note that allprop does not return values for all live properties. WebDAV servers increasingly have expensively-calculated or lengthy properties (see [RFC3253] and [RFC3744]) and do not return all properties already. Instead, WebDAV clients can use propname requests to discover what live properties exist, and request named properties when retrieving values. For a live property defined elsewhere, that definition can specify whether or not that live property would be returned in allprop requests.

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 that does not exist is an error and MUST be noted with a response XML element that contains a 404 (Not Found) status value.

Consequently, the multistatus XML element for a collection resource MUST include a response XML element for each member URL of the collection, to whatever depth was requested. It SHOULD NOT include any response elements for resources that are not WebDAV-compliant. Each response element MUST contain an href element that contains the URL of the resource on which the properties in the prop XML element are defined. Results for a PROPFIND on a collection resource are returned as a flat list whose order of entries is not significant. Note that a resource may have only one value for a property of a given name, so the property may only show up once in PROPFIND responses.

Properties may be subject to access control. In the case of allprop and propname requests, if a principal does not have the right to know whether a particular property exists, then the property MAY be silently excluded from the response.

Some PROPFIND results MAY be cached, with care, as there is no cache validation mechanism for most properties. This method is both safe and idempotent (see Section 9.1 of [RFC2616]).