Comments on -01.1 method defn's
Jim Whitehead (ejw@ics.uci.edu)
Mon, 17 May 1999 16:16:26 -0700
From: Jim Whitehead <ejw@ics.uci.edu>
To: Versioning <ietf-dav-versioning@w3.org>
Date: Mon, 17 May 1999 16:16:26 -0700
Message-ID: <000e01bea0bb$4970a480$d115c380@ics.uci.edu>
Subject: Comments on -01.1 method defn's
Here are some comments on the definitions of new methods in the -01.1
specification.
In general, the elements of a good specification of an HTTP method are:
* It states the expected preconditions of the method, and what happens if
these preconditions are violated. For example, a common precondition is the
resource identified by the Request-URI must exist.
* It states how the arguments for the method are marshalled. For WebDAV,
this includes stating which headers must be present, and which XML elements
are present in the request body.
* It clearly states the semantics of the method's operation.
* It states the postconditions of the method, giving easily validated
postconditions. Some examples of postconditions are effects on the state of
the resource, including body and properties, and effects on the resource's
parent collection. Postconditions will often vary depending on the type of
the resource executing the method.
* It states how the results of the method are marshalled, including the
response for success, and the responses which are generated when the
postconditions cannot be achieved.
* It discusses interactions with other existing methods and resource types.
So, using these as criteria when examining the new methods defined in
the -01.1 spec., the new method definitions fall a little short.
For example, the MKRESOURCE method is defined as (section 4.2.1):
The MKRESOURCE method can be used to create and initialize the properties of
any resource. The body of a MKRESOURCE request has the same syntax as
PROPPATCH. If MKRESOURCE is applied to an existing resource, the result
depends on both the resource type of the existing resource and the resource
type specified in the body of MKRESOURCE. If the protocol does not define
that result, the MKRESOURCE request MUST fail.
This definition falls short in a couple ways:
* It doesn't state what happens at the Request-URI, leaving me to *assume*
this identifies the resource being acted on.
* Since MKRESOURCE can create a resource of any type, I'd expect to see
discussion of how to denotes the new resource's type. I'm left to *assume*
that this is conveyed in the PROPPATCH body. This method also needs to
state which property values must be present, or potentially the default
values which are applied if they are not present. Some property values are
probably not OK to submit (like DAV:getcontentlength).
* The semantics of the method aren't really clear, since the definition
states, "if MKRESOURCE is applied to an existing resource, the result
depends on both the resource type of the existing resource and the resource
type specified in the body of MKRESOURCE" -- this specification isn't
implementable. In particular, it's not clear to me that this kind of
operation is desirable -- how is it different from a plain PROPPATCH?
* Creation of a binding to the parent collection isn't mentioned, an
expected post-condition.
* Response codes aren't defined for either success or failure cases.
* Interactions with MKCOL, MKREF, and PUT aren't discussed.
A better definition would be:
The MKRESOURCE method requests the simultaneous creation of a resource,
identified by the Request-URI, and initialization of its properties.
Creation of the resource and initialization of its properties MUST both
occur, or neither occur. The request message body of the MKRESOURCE method
is the same as for the PROPPATCH method, i.e., it MUST contain the
propertyupdate XML element, defined in section 12.13 of [RFC2518]. The
property update directives in the request message body provide the initial
values of the properties of the new resource. The type of the created
resource is specified by the DAV:resourcetype property, if present. If the
DAV:resourcetype property is not specified, the created resource is an
ordinary (i.e., untyped) resource.
Like PROPPATCH, instruction processing MUST occur in the order instructions
are received (i.e., from top to bottom). Instructions MUST all be executed,
or none executed.
If MKRESOURCE is applied to an existing resource, that resource is deleted
prior to MKRESOURCE processing.
Status Codes:
201 (Created) - The new resource has successfully been created.
207 (Multi-Status) - If any error was encountered in the creation of the
resource, this response is generated. Status codes defined for use with
PROPPATCH (defined in section 8.2.1 of [RFC2518]) SHOULD be used to
represent error cases in setting the value of properties.
This kind of analysis can be extended to the other method definitions as
well. While I realize the intent of this draft is to get broad agreement on
technical direction, rather than nail down all the details, I think it's
important to make early progress on increasing the preciseness of the spec.
- Jim