Skip to main content

8. General Request and Response Handling

8. General Request and Response Handling​

8.1 Precedence in Error Handling​

Servers MUST return authorization errors in preference to other errors. This avoids leaking information about protected resources (e.g., a client that finds that a hidden resource exists by seeing a 423 Locked response to an anonymous request to the resource).

8.2 Use of XML​

In HTTP/1.1, method parameter information was exclusively encoded in HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter information either in an XML ([REC-XML]) request entity body, or in an HTTP header. The use of XML to encode method parameters was motivated by the ability to add extra XML elements to existing structures, providing extensibility; and by XML's ability to encode information in ISO 10646 character sets, providing internationalization support.

In addition to encoding method parameters, XML is used in WebDAV to encode the responses from methods, providing the extensibility and internationalization advantages of XML for method output, as well as input.

When XML is used for a request or response body, the Content-Type type SHOULD be application/xml. Implementations MUST accept both text/xml and application/xml in request and response bodies. Use of text/xml is deprecated.

All DAV-compliant clients and resources MUST use XML parsers that are compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either requests or responses MUST be, at minimum, well formed and use namespaces correctly. If a server receives XML that is not well-formed, then the server MUST reject the entire request with a 400 (Bad Request). If a client receives XML that is not well-formed in a response, then the client MUST NOT assume anything about the outcome of the executed method and SHOULD treat the server as malfunctioning.

Note that processing XML submitted by an untrusted source may cause risks connected to privacy, security, and service quality (see Section 20). Servers MAY reject questionable requests (even though they consist of well-formed XML), for instance, with a 400 (Bad Request) status code and an optional response body explaining the problem.

8.3 URL Handling​

URLs appear in many places in requests and responses. Interoperability experience with [RFC2518] showed that many clients parsing Multi-Status responses did not fully implement the full Reference Resolution defined in Section 5 of [RFC3986]. Thus, servers in particular need to be careful in handling URLs in responses, to ensure that clients have enough context to be able to interpret all the URLs. The rules in this section apply not only to resource URLs in the 'href' element in Multi-Status responses, but also to the Destination and If header resource URLs.

The sender has a choice between two approaches: using a relative reference, which is resolved against the Request-URI, or a full URI. A server MUST ensure that every 'href' value within a Multi-Status response uses the same format.

WebDAV only uses one form of relative reference in its extensions, the absolute path.

Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )

The absolute-URI, path-absolute and query productions are defined in Sections 4.3, 3.3, and 3.4 of [RFC3986].

Within Simple-ref productions, senders MUST NOT:

  • use dot-segments ("." or ".."), or
  • have prefixes that do not match the Request-URI (using the comparison rules defined in Section 3.2.3 of [RFC2616]).

Identifiers for collections SHOULD end in a '/' character.

8.3.1 Example - Correct URL Handling​

Consider the collection http://example.com/sample/ with the internal member URL http://example.com/sample/a%20test and the PROPFIND request below:

Request:

PROPFIND /sample/ HTTP/1.1
Host: example.com
Depth: 1

In this case, the server should return two 'href' elements containing either

  • http://example.com/sample/ and http://example.com/sample/a%20test, or
  • /sample/ and /sample/a%20test

Note that even though the server may be storing the member resource internally as 'a test', it has to be percent-encoded when used inside a URI reference (see Section 2.1 of [RFC3986]). Also note that a legal URI may still contain characters that need to be escaped within XML character data, such as the ampersand character.

8.4 Required Bodies in Requests​

Some of these new methods do not define bodies. Servers MUST examine all requests for a body, even when a body was not expected. In cases where a request body is present but would be ignored by a server, the server MUST reject the request with 415 (Unsupported Media Type). This informs the client (which may have been attempting to use an extension) that the body could not be processed as the client intended.

8.5 HTTP Headers for Use in WebDAV​

HTTP defines many headers that can be used in WebDAV requests and responses. Not all of these are appropriate in all situations and some interactions may be undefined. Note that HTTP 1.1 requires the Date header in all responses if possible (see Section 14.18, [RFC2616]).

The server MUST do authorization checks before checking any HTTP conditional header.

8.6 ETag​

HTTP 1.1 recommends the use of ETags rather than modification dates, for cache control, and there are even stronger reasons to prefer ETags for authoring. Correct use of ETags is even more important in a distributed authoring environment, because ETags are necessary along with locks to avoid the lost-update problem. A client might fail to renew a lock, for example, when the lock times out and the client is accidentally offline or in the middle of a long upload. When a client fails to renew the lock, it's quite possible the resource can still be relocked and the user can go on editing, as long as no changes were made in the meantime. ETags are required for the client to be able to distinguish this case. Otherwise, the client is forced to ask the user whether to overwrite the resource on the server without even being able to tell the user if it has changed. Timestamps do not solve this problem nearly as well as ETags.

Strong ETags are much more useful for authoring use cases than weak ETags (see Section 13.3.3 of [RFC2616]). Semantic equivalence can be a useful concept but that depends on the document type and the application type, and interoperability might require some agreement or standard outside the scope of this specification and HTTP. Note also that weak ETags have certain restrictions in HTTP, e.g., these cannot be used in If-Match headers.

Note that the meaning of an ETag in a PUT response is not clearly defined either in this document or in RFC 2616 (i.e., whether the ETag means that the resource is octet-for-octet equivalent to the body of the PUT request, or whether the server could have made minor changes in the formatting or content of the document upon storage). This is an HTTP issue, not purely a WebDAV issue.

Because clients may be forced to prompt users or throw away changed content if the ETag changes, a WebDAV server SHOULD NOT change the ETag (or the Last-Modified time) for a resource that has an unchanged body and location. The ETag represents the state of the body or contents of the resource. There is no similar way to tell if properties have changed.

8.7 Including Error Response Bodies​

HTTP and WebDAV did not use the bodies of most error responses for machine-parsable information until the specification for Versioning Extensions to WebDAV introduced a mechanism to include more specific information in the body of an error response (Section 1.6 of [RFC3253]). The error body mechanism is appropriate to use with any error response that may take a body but does not already have a body defined. The mechanism is particularly appropriate when a status code can mean many things (for example, 400 Bad Request can mean required headers are missing, headers are incorrectly formatted, and much more). This error body mechanism is covered in Section 16.

8.8 Impact of Namespace Operations on Cache Validators​

Note that the HTTP response headers "Etag" and "Last-Modified" (see [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per resource), and are used by clients for caching. Therefore servers must ensure that executing any operation that affects the URL namespace (such as COPY, MOVE, DELETE, PUT, or MKCOL) does preserve their semantics, in particular:

  • For any given URL, the "Last-Modified" value MUST increment every time the representation returned upon GET changes (within the limits of timestamp resolution).
  • For any given URL, an "ETag" value MUST NOT be reused for different representations returned by GET.

In practice this means that servers

  • might have to increment "Last-Modified" timestamps for every resource inside the destination namespace of a namespace operation unless it can do so more selectively, and
  • similarly, might have to re-assign "ETag" values for these resources (unless the server allocates entity tags in a way so that they are unique across the whole URL namespace managed by the server).

Note that these considerations also apply to specific use cases, such as using PUT to create a new resource at a URL that has been mapped before, but has been deleted since then.

Last updated on