9. HTTP Methods for Distributed Authoring

This chapter describes the HTTP methods defined by WebDAV and extensions to existing HTTP methods.

WebDAV Methods Overview

Method	Purpose	Target
PROPFIND	Retrieve resource properties	Resource or collection
PROPPATCH	Modify resource properties	Resource
MKCOL	Create collection	Unmapped URL
COPY	Copy resource	Source and destination
MOVE	Move/rename resource	Source and destination
LOCK	Lock resource	Resource or collection
UNLOCK	Unlock resource	Locked resource

9.1 PROPFIND Method

PROPFIND retrieves properties defined on the resource identified by the Request-URI.

Request Types:

• propname: Retrieve all property names
• allprop: Retrieve all properties
• prop: Retrieve specific properties
• allprop + include: Retrieve all properties plus additional ones

Example Request:

PROPFIND /file HTTP/1.1
Host: example.com
Depth: 0
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
  <D:prop>
    <D:displayname/>
    <D:getcontentlength/>
  </D:prop>
</D:propfind>

Response: 207 Multi-Status with property values

Depth Header:

• Depth: 0 - Target resource only
• Depth: 1 - Target and direct members
• Depth: infinity - Target and all descendants

9.2 PROPPATCH Method

PROPPATCH modifies properties on a resource.

Operations:

• set: Create or update property
• remove: Delete property

Example:

PROPPATCH /file HTTP/1.1
Host: example.com

<?xml version="1.0" encoding="utf-8" ?>
<D:propertyupdate xmlns:D="DAV:">
  <D:set>
    <D:prop><D:displayname>New Name</D:displayname></D:prop>
  </D:set>
  <D:remove>
    <D:prop><D:author/></D:prop>
  </D:remove>
</D:propertyupdate>

Atomicity: All operations MUST succeed or fail together.

9.3 MKCOL Method

MKCOL creates a new collection resource at the Request-URI.

Example:

MKCOL /new-collection/ HTTP/1.1
Host: example.com

Requirements:

• Request-URI MUST be an unmapped URL
• Parent collection MUST exist
• Request body SHOULD be empty (or MAY contain content type info)

Status Codes:

• 201 Created - Collection successfully created
• 403 Forbidden - Resource already exists at URL
• 409 Conflict - Parent collection does not exist

9.4 GET, HEAD for Collections

When applied to a collection, GET and HEAD MAY return:

• HTML directory listing
• Collection member listing
• Empty body

The behavior is implementation-specific.

9.5 POST for Collections

POST for collections is used to add members. The server determines the new member URL.

9.6 DELETE Method

DELETE removes the resource identified by Request-URI.

For Collections:

• Deletes the collection and all members recursively
• If Depth: infinity header is omitted, behavior is equivalent to Depth: infinity

Partial Failure: If deletion of any member fails, the entire operation fails (atomicity required).

9.7 PUT Method

PUT creates or updates a resource.

Write Lock Interaction:

• If target is locked, client MUST submit appropriate lock token in If header
• Creates lock-null resources if LOCK was used on unmapped URL

9.8 COPY Method

COPY creates a duplicate of the source resource at the destination.

Headers:

• Destination: Target URL (required)
• Depth: 0 or infinity (default: infinity)
• Overwrite: T (true) or F (false) (default: T)

Example:

COPY /source HTTP/1.1
Host: example.com
Destination: http://example.com/dest
Overwrite: F
Depth: infinity

Behavior:

• Copies resource content and dead properties
• Live properties handled according to their definitions
• Collection copies are recursive (with Depth: infinity)
• Locks are NOT copied

Status Codes:

• 201 Created - Destination created
• 204 No Content - Destination overwritten
• 207 Multi-Status - Partial success (some members failed)
• 412 Precondition Failed - Overwrite: F and destination exists

9.9 MOVE Method

MOVE is logically equivalent to COPY + DELETE.

Example:

MOVE /old-location HTTP/1.1
Host: example.com
Destination: http://example.com/new-location
Overwrite: T

Behavior:

• Moves resource to destination
• Updates all URLs referencing the resource
• Properties are preserved
• Locks on source are removed
• Destination is NOT locked after move

Atomicity: MOVE operations MUST be atomic (not split into COPY + DELETE).

9.10 LOCK Method

LOCK obtains a lock on a resource.

Lock Types:

• Exclusive write lock: Only one principal can hold
• Shared write lock: Multiple principals can hold

Example:

LOCK /resource HTTP/1.1
Host: example.com
Timeout: Second-3600
Depth: 0

<?xml version="1.0" encoding="utf-8" ?>
<D:lockinfo xmlns:D="DAV:">
  <D:lockscope><D:exclusive/></D:lockscope>
  <D:locktype><D:write/></D:locktype>
  <D:owner>
    <D:href>http://example.com/user</D:href>
  </D:owner>
</D:lockinfo>

Response: 200 OK with lockdiscovery property containing lock token.

Lock Refresh: Submit LOCK with lock token in If header and no body.

9.11 UNLOCK Method

UNLOCK removes the lock identified by the lock token.

Example:

UNLOCK /resource HTTP/1.1
Host: example.com
Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>

Requirements:

• Lock-Token header MUST contain the lock token
• Only the lock creator or privileged principal can unlock

Status Codes:

• 204 No Content - Lock successfully removed
• 409 Conflict - Resource was not locked
• 423 Locked - Resource locked by different token

---

For complete method specifications, error handling, and detailed examples, refer to RFC 4918 Sections 9.1-9.11.