Re: More feedback on WADL

Thanks for the review, comments and responses inline below.

On Jul 21, 2005, at 2:25 PM, Mark Nottingham wrote:
>
> * 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.
>
Works for me, that's certainly the intent.

> 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."
>
Fair enough, I was just trying to capitalize on the relative well- 
known-ness of WSDL to position WADL but I take your point.

> 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.
>
Again, I take your point and will modify as suggested.

>
> * 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.
>
It was intended as a container for any type of description. Types is  
perhaps a bad choice of name, schemas might be better. I'm not sure  
about making it schema specific though, since I'd expect the child  
elements to convey the type of schema language (XSD, RelaxNG, etc).

>
> * 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?
>
The intent was to be able to include a schema (with a small s)  
document rather than having to inline it.

>
> * 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>
>
Yep, that sounds good to me.

> 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).
>
OK, I'd assumed that that kind of parameter would only be defined in  
the 'leaf' resource elements rather than supporting any kind of  
parameter cascading.

>
> 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">...
>
Right, the operation thing was to allow you specify a name for the  
combination of resource, HTTP method and request. For GET these tend  
to collapse to a single meaning but for POST you can thinks in terms  
of different operations based on request contents. Make sense ?

> 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?
>
Yes, see my comment above for why I think that makes sense. I'll try  
to make this more explicit in the text.

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

>
> 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)
>
I didn't miss these, it was a deliberate choice. Use of ID for the  
parameter name would restrict you to only having one parameter with a  
particular name per description whereas I think many resource URIs  
could have the same query parameter name. Parameters are not  
something that get cross referenced within a description so there's  
no need to use ID. The use of NMTOKEN was a (perhaps vain) attempt to  
constrain the value space to be useable as a query .

> 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.
>
OK.

> Shouldn't the semantic expressed by the repeating attribute be  
> function of the referenced type definition?
>
Not sure what you mean, can you elaborate ?

> 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?
>
Two different senses. I wanted to support generative URIs like:

http://example.com/widgets/${widgetId}

as well as  URIs like

http://example.com/widgets/${widgetId}?foo=bar

The idea is that if a parameter name matches one embedded in the URI  
then you don't append the ?name= bit, you just substitue the value in  
the URI, if theres no match then you append the query parameter.

E.g. if you have two parameters: widgetId and foo with values 10 and  
bar respectively then:

uri="http://example.com/widgets/${widgetId}" -> http://example.com/ 
widgets/10?foo=bar
uri="http://example.com/widgets" -> http://example.com/widgets/10? 
widgetId=10&foo=bar

> 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>
>
I'm not sure I understand the design here, is foo:myResourceName a  
path segment that is expected to be substituted for some value at  
runtime ?

> 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.
>
Again, I'm not sure I understand, do you mean that you'd disallow  
something like


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

And require an extra resource element for the "widgets" path segment ?

>
> 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.
>
Either works, I just found my XSLT simpler when the element name was  
different but I could go either way, what do other folks think ?

>
> 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?
>
Given your Operation->Method change I'd agree but given my  
clarification about why I put in operation then maybe not. The idea  
was to provide a construct to group a common set of operations  
together that can be applied to multiple resources but perhaps this  
is outside the 80/20 mark.

>
> 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..."
>
Right.

> 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.
>
I went with element since its schema language independent, you just  
provide the qualified name of the element and any schema language can  
be used to provide a description of that.

>
> 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?
>
A bad application design perhaps ;-).

> 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.
>
Agreed.

>
> 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?
>
Yes, although as I've explained I was trying to keep it format  
independent. Perhapos a section on use with XSD and another on use  
with RelaxNG would be appropriate.

> 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?
>
Certainly/

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

Thanks again for the detailed review.

Cheers,
Marc.

---
Marc Hadley <marc.hadley at sun.com>
Business Alliances, CTO Office, Sun Microsystems.