More feedback on WADL

I read the 2005-05-24 draft of WADL some time ago, but have only now  
had a chance to write down my comments; sorry for the delay.

Overall, this draft is looking really good. Here are a few things I  
noticed / remaining areas of concern:

* The abstract positions WADL as a "simple alternative to WSDL for  
use with XML/HTTP Web applications." One small improvement, based on  
list discussion, would be to say that it's "for use with HTTP-based  
Web applications, especially those using XML" to reflect that non-XML  
use cases are also in-bound.

Also, I'm concerned about couching it as a WSDL replacement; that  
format evokes, for better or worse, a number of images in people's  
minds, and I'm not at all confident that WSDL's place in the SOA/RPC  
world is the same as that which a Web description language should  
take. In particular, the use cases (which I do think we should  
discuss much more!) may be different, as may the nature of the  
format's use -- people often refer to WSDL as 'the contract', which I  
believe is an inappropriate way to position a Web description format.

Similar language is also in the Introduction; e.g., "It aims to fill  
the same gap for XML/HTTP-based applications that WSDL fills for SOAP- 
based Web services."

Finally, the last sentence, "WADL aims to privde a machine process- 
able description of such applications" draws one to believe that it's  
an IDL, which in fact I think it would be much closer to say that  
it's a *protocol* description format, for use with Web applications.  
I know it looks like a minor change, but the shift in thinking is huge.


* 2.2 Types -- can this section contain definitions from any type  
system (e.g., XML Schema, RelaxNG, OWL, BNF, etc.) or just XML  
Schema? My preference, I think, is to call it "schemaTypes" and make  
it Schema-specific.


* 2.2.1 Include says that this element is to be used to allow "a  
resource state representation description to be included by  
reference." How does that work, considering that this is in the  
context of the types section? I would have understood if you were  
referring to externally-sourced type definitions, but that doesn't  
seem to be the case. Was the intent to allow inclusion of an abstract  
type for reuse?


* 2.3.1 Resources - I think it would be useful to have a 'base'  
attribute on resources that allows you to set a base for a set of  
resources; e.g.,

<resources base="http://www.example.com/">
   <resource uri="widgets">
     <resource uri="/${widgetid}"/>
   </resource>
</resources>

The other thing that came to mind here was that because you allow  
parameters to be in the uri attribute (e.g., <resource uri="http:// 
www.example.com/widget?foo=bar"/>), it's a little ambiguous for  
resource element children of that resource element. You probably need  
to reference the appropriate part of the URI spec to explain how to  
walk the tree of resource elements (but see below first for other  
concerns about this structure in general).


2.4 Operation - Since it's HTTP-specific, why not call this method?  
Operation is very WSDL/RPC-ish. Perhaps something like <method  
name="GET" id="fooGET">...

WADL also needs to say whether it's permissible for a resource to  
have more than one operation (or method :) element with the same  
name; i.e, can I have two POST handlers on the same resource?


2.4.1 Request should explicitly say that multiple representation  
elements indicate alternatives that the resource will accept.


2.4.2 Request Parameters still uses NMTOKENs and QNames for  
identification; did you miss these in the conversion to URIs? (See  
also 2.6.1)

This section needs to reference the HTML name/value pair format for  
the query parameters (don't have the ref now, on a plane); although  
it's extremely common practice, it's not mandated by either URIs or  
HTTP; it's format-specific.

Shouldn't the semantic expressed by the repeating attribute be  
function of the referenced type definition?

WRT URI Component Substitution -- what's the use case for this? It  
seems to make implementation more complex, and I'm thinking a cleaner  
separation between the resource identity and the parameters to it, by  
confining the parameters to the request section. Or are you using  
'parameters' in two different senses?

My preferred solution would be to constrain the resource element to  
path segments only, leaving query parameters in the request  
description, and differentiate between static path segments and  
generative names with a 'type' attribute, like this:

<resources base="http://www.example.com/">
    <resource name="widgets/">
       <resource type="foo:myResourceName">
           <method name="GET">
              <request>
                  <parameter name="myParam" type="my:paramType"/>
              </request>
           </method>
       </resource>
    </resource>
</resources>

Furthermore, I'd prefer to constrain the resource element to be  
associated with *one* path segment only, so that there's a stronger  
link between Web resources and XML structures describing them (and,  
eventually, code implementing them).

I know that's a big change (and I may have already mentioned it), but  
I'd like to weigh the two approaches against each other in discussion.


2.4.3 Response -- I'd prefer to collapse representation/ 
representationRef and fault/faultRef into single elements, with  
different attributes based on whether they're by-value or by- 
reference. This is just stylistic preference/syntactic sugar; see  
<http://www.mnot.net/blog/2005/06/14/uris_not_qnames> for the details  
of my preferred pattern.


2.5 Operation Group -- what's the utility of this? With the other  
modularity mechanisms available, and given the small number of  
operations that REST implies, I can't imagine a scenario where this  
would be really useful. What am I missing?


2.6 Representation - "A representation element describes the  
representation of a resource's state..." -> "A representation element  
describes *a* representation of a resource's state..."

WRT the element attribute, I could see this go in two directions. One  
would be to make it schema-specific, in which case it should be  
called 'rootSchema' or similar; other type systems could use other  
attributes. The other approach would be to call it just 'type' and  
let any type system use it. I think I prefer the first approach,  
because I have concerns about how workable the second is.


2.7 Fault - "a list of HTTP status codes..." what does it mean when  
there is more than one HTTP status code associated with a fault?

Also, it would be good to give guidance about the relationship of  
declared Faults to those on the wire, as discussed on the list earlier.


A few general questions/comments -

* What do you think about moving the format-specific sections to a  
separate part of the spec, so it's more clear that other formats and  
data models can be used with it?

Also, if I wrote up a straw-man way to hook OWL and RDF Schema  
descriptions of content into WADL as a peer of types/element (or, as  
I'd prefer, schemaTypes/rootSchema), would you consider including it  
in the spec?


* I'd be a lot more comfortable if extensibility were explicitly  
allowed (and explained) in the prose, and not the Schema.


Cheers,

--
Mark Nottingham     http://www.mnot.net/

Received on Thursday, 21 July 2005 18:25:12 UTC