6.2 MKCOL: Create Collection

A collection on a WebDAV server acts as a container for resources. The name of the collection always appears in the URLs for resources inside it, determining part of the path to the resource. MKCOL is used to create new collections inside existing collections.

To create a collection, the client first builds the URL for the new collection by appending the new collection's name onto the parent collection's URL. It then sends a MKCOL request to the constructed URL (see Listing 6-1).

Why MKCOL Is Not PUT

The PUT method is already used to create new resources. Why not reuse PUT to create a collection? One reason is that PUT might conceivably have its own meaning and behavior for a collection, different from the behavior for MKCOL. Collections may have members, but there's no technical reason that collections may not also have document bodies, just like regular resources. PUT could then be used to create or modify the collection's document content. This is not part of the standard, because many file systems have nowhere to store this document yet, but the possibility was envisioned by the WebDAV designers.

Listing 6-1 MKCOL request and response.

Request:

 MKCOL /hr/recruiting HTTP/1.1 Host: www.example.com  

Response:

 HTTP/1.0 201 Created Date: Sun, 29 Jul 2001 15:24:17 GMT Content-Length: 0  

The server created a collection named recruiting inside the existing collection hr. The parent collection hr must already exist, but recruiting must not. If a resource named recruiting already exists, whether it's a collection or not, the request will fail.

The MKCOL request does not need a body, because there's no need for additional information to create a collection. However, extensions to WebDAV may use a body, so WebDAV servers must be able to handle request bodies gracefully. If the server does not expect to see a request body, it may not look for one, and can treat the request as if it does not have a body. If the server does expect a request body but not one of the kind the client sent, it may return a 415 Unsupported Media Type status.

6.2.1 MKCOL and the Allow Header

The OPTIONS response for a collection typically does not show the MKCOL method in the Allow header (as shown in Listing 5-2). The HTTP specification is unclear what Allow means semantically. The WebDAV specification doesn't clarify either it doesn't mention how to treat the MKCOL method in the Allow header.

A MKCOL request to a URL for a collection that does exist must fail because MKCOL is not allowed to overwrite existing collections. Some implementors reason that MKCOL is forbidden on existing collections, thus it should not appear in the Allow header. Other implementors reason that since MKCOL is allowed to create a new collection within a parent collection, MKCOL should appear.

Following the same lines of reasoning, it's also unclear whether PUT should appear in the Allow header for a collection. Although a server may forbid PUT directly on a collection URL, it may allow PUT to create new resources within the collection.

Clients must be prepared for either behavior and not assume that MKCOL isn't allowed just because it doesn't show up. An OPTIONS request to the magic * URL should of course show MKCOL as an allowed method, because in that case, all methods supported anywhere on the server are shown. Server implementations do seem to handle the Allow header correctly in responses to OPTIONS * that is, if the server supports OPTIONS * at all.

6.2.2 Status Codes for MKCOL

The successful response to a MKCOL request is always 201 Created.

The server may refuse a MKCOL request for the usual reasons: locks are involved, permission is denied, the server couldn't match conditions provided by client, and so forth. There are also a number of special reasons that a MKCOL request can be a failure:

• 403 Forbidden: The server does not allow the creation of a collection at this location. For example, some implementations might forbid creation of subcollections inside a "trash" folder or other special-purpose collection.

• 405 Method Not Allowed: The MKCOL method is not allowed on this resource. This would be the case for any resource that already existed, because MKCOL is only allowed on null resources or unmapped URLs.

• 409 Conflict: The parent collection does not exist, or a resource exists with the parent's name but it is not a collection.

• 415 Unsupported Media Type: The server does not support a body on the MKCOL request, or it does not support a body of the type sent by the client. Most server implementations either ignore a MKCOL request body or use this error, as WebDAV does not define a body for MKCOL requests. Server implementors should use the error because it's not safe to ignore request bodies that aren't recognized.