Is it a good idea to make your WADL available?

[Mark Nottingham-4]

As I've said before, my primary use cases for WADL (and other desc  
formats) are
   a) as a design-time aid
   b) for documentation generation
   c) for server and intermediary configuration
and possibly also for stub generation on the server side.

Talking to folks about this, I'm starting to wonder if there are  
*any* good use cases for sharing your Web description with clients,  
because doing so risks engendering tight coupling.

The only exception I can think of right now is when you can do some  
client-side optimisation (e.g., having hints about whether the  
service supports chunked/compressed request bodies). However, that  
information can be made available elsewhere (e.g., OPTIONS extensions).

Thoughts?

Of course, we can't stop people from misusing description, but I'd  
like to have the clearest, strongest guidance possible available and  
well-known, so this doesn't lead people down the same path that WS-*  
took (to parrot one concern I've heard).

Cheers,

--
Mark Nottingham
mnot@...

[Danny Ayers]

On 8/31/06, Mark Nottingham <mnot@...> wrote:

>
> As I've said before, my primary use cases for WADL (and other desc
> formats) are
>    a) as a design-time aid
>    b) for documentation generation
>    c) for server and intermediary configuration
> and possibly also for stub generation on the server side.
>
> Talking to folks about this, I'm starting to wonder if there are
> *any* good use cases for sharing your Web description with clients,

Sorry Mark, maybe I'm missing something here, but wasn't the original
idea to encourage client (machine)-readable descriptions? Point a
fairly generic client the WADL, it has some notion what to expect.

I guess there's a grey area between where the description is used to
create a client-side stub, which gets hand(hard)-coded on top of,
though...

> because doing so risks engendering tight coupling.

...but if the client was to some extent self-configuring from the
supplied description, if the description changed, so would the
client..?

Cheers,
Danny.

--

http://dannyayers.com

[Marc Hadley]

On Aug 31, 2006, at 4:02 PM, Mark Nottingham wrote:

>
> As I've said before, my primary use cases for WADL (and other desc  
> formats) are
>   a) as a design-time aid
>   b) for documentation generation
>   c) for server and intermediary configuration
> and possibly also for stub generation on the server side.
>
> Talking to folks about this, I'm starting to wonder if there are  
> *any* good use cases for sharing your Web description with clients,  
> because doing so risks engendering tight coupling.
>
> The only exception I can think of right now is when you can do some  
> client-side optimisation (e.g., having hints about whether the  
> service supports chunked/compressed request bodies). However, that  
> information can be made available elsewhere (e.g., OPTIONS  
> extensions).
>
> Thoughts?
>
> Of course, we can't stop people from misusing description, but I'd  
> like to have the clearest, strongest guidance possible available  
> and well-known, so this doesn't lead people down the same path that  
> WS-* took (to parrot one concern I've heard).
>

I think you should leave it up to clients to decide how they choose  

to use the information you provide. Not providing a WADL in order to  
protect clients from themselves seems a little self defeating - you  
have to provide information in some form to make your service  
useable. Just providing an XSD for the XML documents your service  
uses is enough information for someone to come up with some very  
tightly coupled client code.

Provided you clearly spell out the expectations in terms of  
longevity, versioning policy etc, I see little harm in providing a  
public description of your service.

Marc.

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

[Tim Bray-3]

On Aug 31, 2006, at 1:02 PM, Mark Nottingham wrote:

>
> As I've said before, my primary use cases for WADL (and other desc  
> formats) are
>   a) as a design-time aid
>   b) for documentation generation
>   c) for server and intermediary configuration
> and possibly also for stub generation on the server side.
>
> Talking to folks about this, I'm starting to wonder if there are  
> *any* good use cases for sharing your Web description with clients,  
> because doing so risks engendering tight coupling.

I always thought of WADL as kind of "The .h file for my Web app".  I  
think the rewards outweigh the risks. -Tim

[Mark Nottingham-4]

Imagine that you're going to take a trip this weekend (especially  
relevant for the US folks). You can either;

   a) Get onto your local freeway and hope to get where you want by  
following the signs, based on what you know.

   b) Navigate only using a map (maybe you've got a fancy in-car  
GPS), with your headlights off.

   c) Plan your trip on a map, but navigate by signs and landmarks  
you see while you're on the road.

(a) is how the Web works for people, but it isn't really practical  
for machines (yet). (b) is how most WS-* tools work. (c) is what I'd  
like to encourage (without explicitly disallowing (b), although I'm  
not sure I want to be on the same road as them!).

People will always write broken tools, but what I'm really concerned  
about is that people will write Web applications that *require* a  
description file to navigate/use; i.e., there will be (meta-)data in  
there that won't be in representations. For example, people might  
start wondering why they need all of those pesky <link> elements and  
other metadata in Atom documents when they've got a description file  
that contains all.

What might help is concrete guidance about what shouldn't be in a  
WADL file, and what shouldn't be only in a WADL file. Does that seem  
reasonable?

Also, I've heard lots of people talk about consuming WADL on the  
client side, but no concrete proposals for what the use would entail.  
Are people assuming that they'll look at a WADL, generate some code,  
and then blindly make requests for URLs according to it? Or would the  
WADL be re-checked at runtime? Or...?

Cheers,

--
Mark Nottingham
mnot@...

[David Orchard]

This topic is one of many unfinished Roy conversations that I wish I had
more time for.  He is against web description languages for the reason
of increasing the coupling between systems.  I never really got to dig
into why he believes that.  

Having said that, I think that description languages make it easier to
deploy a more scalable ( in terms of # of resources) system.  

Let's take a very simple example, providing the schema type for the http
GET result of a particular URI, aka an association between a URI and
it's represenation's schema.  Most systems right now say in text things
like, "if you get this URI, you'll get back a document that meets this
particular schema".  So the developer then handcodes that association.
If the schema ever changes, then they will have to go in and change it
by hand - and they'll find out when they break.  OR if backwards compat
is preserved then there will be a new URI for a new schema that they
won't know about until they go trolling through the docs.  

If you have a description language, the association between URI and
schema for result can be automated and that includes the evolution of
the contract.  For small #s of URIs, that's might not be that big a
deal.  For large #s of resources, that becomes a big deal.  

Now I ask, "How is an automated association between representation
schema and URI more tightly coupled than a human discovered
association?"  To be clear, I'm not talking about strong-typing, I'm
talking about simply the association.  You can make either of these
strong or loosely typed by how you design the schema.  The question is
about coupling of the association itself.

I think that these are equally coupled.  In either scenario, if the
service changes the client may break or miss something.  I do think it
affects a different "property of interest", which is ease of development
and scalability of components.  

You *could* argue that having an association between URI and
represenation schema will lead people to build more brittle software
because they will do something different in their design, but I think
that's going to be a tough one to argue.  

I say yay verily, publish any and all Web Description Languages.

Cheers,
Dave

> -----Original Message-----
> From: public-web-http-desc-request@...
> [mailto:public-web-http-desc-request@...] On Behalf Of
> Mark Nottingham
> Sent: Thursday, August 31, 2006 1:03 PM
> To: public-web-http-desc@...
> Subject: Is it a good idea to make your WADL available?
>
>
> As I've said before, my primary use cases for WADL (and other desc
> formats) are
>    a) as a design-time aid
>    b) for documentation generation
>    c) for server and intermediary configuration and possibly
> also for stub generation on the server side.
>
> Talking to folks about this, I'm starting to wonder if there are
> *any* good use cases for sharing your Web description with
> clients, because doing so risks engendering tight coupling.
>
> The only exception I can think of right now is when you can
> do some client-side optimisation (e.g., having hints about
> whether the service supports chunked/compressed request
> bodies). However, that information can be made available
> elsewhere (e.g., OPTIONS extensions).
>
> Thoughts?
>
> Of course, we can't stop people from misusing description,
> but I'd like to have the clearest, strongest guidance
> possible available and well-known, so this doesn't lead
> people down the same path that WS-* took (to parrot one
> concern I've heard).
>
> Cheers,
>
> --
> Mark Nottingham
> mnot@...
>
>
>
>
>

[Danny Ayers]

I think Mark's question over what "risks engendering tight coupling"
makes sense as a question. But presumably there's a spectrum between
no coupling (i.e. zero communication) and total coupling (they speak a
private language). I suspect whether the description are expressed in
human or machine language is orthogonal.

The argument against tight coupling isn't that it inhibits
communication, because by definition this improves communication
between the parties that subscribe to the specific contract. But in
practice tight coupling is exclusive, anyone that doesn't speak the
private language can't come in. But when there's looser coupling, then
the information transfer efficiency (no, maybe effectivity?) is
reduced by virtue of mustIgnores. The 404 is an ideal contract, but
it's no-win.

The To: line here has "web" in it, so presumably we're in the context
of an enormously distributed environment (I slip into a platitude
voice sometimes, sorry). In such an enviroment is it more likely that
there will be excessive couplement (!?) or isolation?

Dunno, I can't find the right bones. But my gut says that if you want
to connect things together:

On 9/1/06, David Orchard <dorchard@...> wrote:

> I say yay verily, publish any and all Web Description Languages.

Cheers,
Danny.

--

http://dannyayers.com

[Paul Downey]

Mark wrote:
>
> Of course, we can't stop people from misusing description,

.. I'm wondering how I'd know I was misusing a description'?

I suspect this is more of an versioning/obligation issue -
ideally clients should be aware that an interface described by
a WADL is subject to changes within the rules of RFC2616 ..

Or maybe my site may take a policy that the WADL is a
fixed contract which may be relied upon not to change?

--
http://blog.whatfettle.com

[distobj]

Marc,

On 8/31/06, Marc Hadley <Marc.Hadley@...> wrote:
> I think you should leave it up to clients to decide how they choose
> to use the information you provide. Not providing a WADL in order to
> protect clients from themselves seems a little self defeating - you
> have to provide information in some form to make your service
> useable.

And there's the rub.  In a RESTful system, that information is
contained within the data consumed by your application; forms and
links.  If you *also* put that information in a document not intended
for application consumption, then at best you've duplicated
information, and at worse you've confused your clients as to what's
authoritative.

Mark.

[noah_mendelsohn]

I think we're thrashing in part because we're speaking very broadly of
descriptions, which could in principle be at many different levels.
Clearly, data conveyed in response to a GET is authoritative, and is to be
honored in preference to anything found in an external description.
Clearly the Web becomes much more fragile if description languages go
beyond giving advance notice of the likely characteristics of a resource,
and instead add information (e.g. default values, units for monetary
values) that is essential to the correct interpretation of
representations.  Furthermore, Mark Baker is right IMO that, when in
doubt, we should build software that can react dynamically to the widest
possible range of representations and metadata.  That's the purest (and
the purist :-) ) approach.

That said, we all have expectations for the resources with which we
interact, and I don't think it's a bad thing for such expectations to be
set out in machine readable form, again where practical.  Not all Web
software is general purpose, and it's useful to be able to in advance the
configuration of such software.  So, I think it's worth roughly
categorizing the sorts of things that we think we want to know about a
resource before we interact with it:

I.  Roughly what is this resource and what is it for?  If I have a link
that I expect will be to my hotel reservation, there's very little chance
that anyone needs a Web so dynamic that the same link will tomorrow be to
representations of my car's muffler or to someone's resumé.  True, it's
useful to have Web software that can deal with any of those, but it's also
reasonable for certain purposes to have locked in general expectations
about the nature of a resource.  Insofar as Web descriptions help to
establish such broad expectations as to the nature of a resource, I think
they are mostly of low risk.

II.  What general middleware technology is likely to be used to represent
the resource?  Are we talking about a static HTML page or one with
JavaScript?  Next year might the representation come back with embedded
Flash?  Are we using application/xml or RDF triples?  I think history
shows that these choices do change over time.  The URI that served very
simple HTML 10 years ago may later have tried frames, moved on to
JavaScript, may now be Flash-enabled, etc.   While it's reasonable to note
that these choices tend to change slowly, and perhaps to capture hints
about current choices in Web Descriptions to maximize the chance that
clients are suitably configured, it's a very good thing if client software
can adapt as the resource evolves to represent itself using different
technologies.

III. What are the detailed expectations for the content?  For formats like
XML, what exact format is being used, e.g. to represent the hotel
reservation?  What is the schema for the XML tags?   Do the telephone
numbers have country codes?  Is there an advertisement at the top of the
page?  Breadcrumbs?  These sorts of details are probably the most likely
to evolve at a rapid rate, yet they are the ones most likely to be
captured in something like an XML Schema.   If a given client isn't
reasonably robust to mismatched expectations about such details, it's
likely to break frequently.

I'm sure you can slice things differently, but I think it's important to
make distinctions like this in deciding what is reasonable to agree on out
of band, vs. what should be discovered only dynamically from a returned
representation, from HTTP headers, etc.  Though I'm not sure it's what
most of us are focussing on, I think that having advance agreements at the
(I.) level is often reasonable.  There are many circumstances in which one
will say "look, the technology may change over time, and the detailed
schemas may change over time, but if this doesn't point to a hotel
reservation, then there's no reason for me to be talking to you."

As you work your way toward the higher numbers in the list above, then you
wind up building increasing fragile systems as you use out-of-band means
to establish anything more than hints.  In any case, I think the guiding
principles should be:  individual interactions on the Web should in all
cases be self-describing.  Any out of band description should be viewed as
a hint, but for certain sorts of contracts it may be reasonable to assume
that a mismatch between the external description and the representation
metadata is a fatal error.  Particularly as descriptions are used to
capture technology details or data representations that are likely to
change, it's important that systems be capable of successful operation in
cases where the external descriptions are in error.  In all cases,
metadata conveyed with the interaction is authoritative.

--------------------------------------
Noah Mendelsohn
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------

[Sanjiva Weerawarana-2]

Mark Baker wrote:
>
> And there's the rub.  In a RESTful system, that information is
> contained within the data consumed by your application; forms and
> links.  If you *also* put that information in a document not intended
> for application consumption, then at best you've duplicated
> information, and at worse you've confused your clients as to what's
> authoritative.

Same battle new forum .. hi Mark ;-).

I don't understand you at all - so its ok to put the info in English (or
Korean or Sinhalese) but its not ok to put it in XML in a machine
processable format??

Do you think that (obviously crazy) programmers don't read English (or
Korean or Sinhalese) and *couple* their programs to the services thus
described? Or do you think that because you don't put it down in XML that
they hand write magic self learning code that can handle any change in the
data dynamically?

Its easy to do this stuff when there's a smart agent like a human in front
of course. When there's no human in the loop the problem is a just a tad
harder.

Sanjiva.
--
Sanjiva Weerawarana, Ph.D.
Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
email: sanjiva@...; cell: [phone]; fax: [phone]

"Oxygenating the Web Service Platform."

[Marc Hadley]

If I might channel Mark for a moment (Mark, I'm sure you'll jump in  
if I misinterpret), I think there's an unstated assumption in his  
reasoning that might clarify things. AIUI, Mark believes that there  
will/should only be a few standard formats in use (e.g. Atom for list-
type data, XHTML for form type data etc) and that such a constrained  
world is more amenable to general-purpose processing modules, one per  
format, each of which fully groks the format it is intended to  
process and the semantics of data and metadata contained therein.

Personally, even if the above turns out to be the dominant paradigm,  
I still think there's utility in setting out a map of the available  
resources and their supported methods and representations and with  
APP and OpenSearch we already have existence proof that such  
descriptions are useful. I just hope we can avoid a plethora of such  
description languages.

Marc.

On Sep 4, 2006, at 4:39 AM, Sanjiva Weerawarana wrote:

>
> Mark Baker wrote:
>> And there's the rub.  In a RESTful system, that information is
>> contained within the data consumed by your application; forms and
>> links.  If you *also* put that information in a document not intended
>> for application consumption, then at best you've duplicated
>> information, and at worse you've confused your clients as to what's
>> authoritative.
>
> Same battle new forum .. hi Mark ;-).
>
> I don't understand you at all - so its ok to put the info in  
> English (or Korean or Sinhalese) but its not ok to put it in XML in  
> a machine processable format??
>
> Do you think that (obviously crazy) programmers don't read English  
> (or Korean or Sinhalese) and *couple* their programs to the  
> services thus described? Or do you think that because you don't put  
> it down in XML that they hand write magic self learning code that  
> can handle any change in the data dynamically?
>
> Its easy to do this stuff when there's a smart agent like a human  
> in front of course. When there's no human in the loop the problem  
> is a just a tad harder.
>
> Sanjiva.
> --
> Sanjiva Weerawarana, Ph.D.
> Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
> email: sanjiva@...; cell: [phone]; fax: [phone]
>
> "Oxygenating the Web Service Platform."
>

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

[janalgermissen1und1]

Marc,
 
On Tuesday, September 05, 2006, at 02:58PM, Marc Hadley <Marc.Hadley@...> wrote:

>If I might channel Mark for a moment (Mark, I'm sure you'll jump in  
>if I misinterpret), I think there's an unstated assumption in his  
>reasoning that might clarify things. AIUI, Mark believes that there  
>will/should only be a few standard formats in use (e.g. Atom for list-
>type data, XHTML for form type data etc) and that such a constrained  
>world is more amenable to general-purpose processing modules, one per  
>format, each of which fully groks the format it is intended to  
>process and the semantics of data and metadata contained therein.
>
>Personally, even if the above turns out to be the dominant paradigm,  
>I still think there's utility in setting out a map of the available  
>resources and their supported methods and representations

IMO, the right way to create such a description is to have it generated by a client that
excercises the application and keeps track of the current state machine. Generating it has
two advantages: it emphazises the possible instability of that information and it provides a
fine impression of what the contract really is that the client can rely on (IOW: what is not
runtime-discoverable or in the HTP specs must not be known).

It can also show places, where additional contract is required for machine clients to excercise the
application.


Jan


and with  

>APP and OpenSearch we already have existence proof that such  
>descriptions are useful. I just hope we can avoid a plethora of such  
>description languages.
>
>Marc.
>
>On Sep 4, 2006, at 4:39 AM, Sanjiva Weerawarana wrote:
>
>>
>> Mark Baker wrote:
>>> And there's the rub.  In a RESTful system, that information is
>>> contained within the data consumed by your application; forms and
>>> links.  If you *also* put that information in a document not intended
>>> for application consumption, then at best you've duplicated
>>> information, and at worse you've confused your clients as to what's
>>> authoritative.
>>
>> Same battle new forum .. hi Mark ;-).
>>
>> I don't understand you at all - so its ok to put the info in  
>> English (or Korean or Sinhalese) but its not ok to put it in XML in  
>> a machine processable format??
>>
>> Do you think that (obviously crazy) programmers don't read English  
>> (or Korean or Sinhalese) and *couple* their programs to the  
>> services thus described? Or do you think that because you don't put  
>> it down in XML that they hand write magic self learning code that  
>> can handle any change in the data dynamically?
>>
>> Its easy to do this stuff when there's a smart agent like a human  
>> in front of course. When there's no human in the loop the problem  
>> is a just a tad harder.
>>
>> Sanjiva.
>> --
>> Sanjiva Weerawarana, Ph.D.
>> Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
>> email: sanjiva@...; cell: [phone]; fax: [phone]
>>
>> "Oxygenating the Web Service Platform."
>>
>
>---
>Marc Hadley <marc.hadley at sun.com>
>Business Alliances, CTO Office, Sun Microsystems.
>
>
>
>

------------------------------------------------------------
Jan Algermissen                                               http://jalgermissen.com
Software Architect                                            http://www.tugboat.de

[mnot]

On 2006/09/05, at 5:57 AM, Marc Hadley wrote:

> Personally, even if the above turns out to be the dominant  
> paradigm, I still think there's utility in setting out a map of the  
> available resources and their supported methods and representations  
> and with APP and OpenSearch we already have existence proof that  
> such descriptions are useful. I just hope we can avoid a plethora  
> of such description languages.

Well, *this* Mark agrees. However, as I tried to explain in my  
previous message WRT maps, it's the way that it's used -- on the  
server side as well as client side -- that's important.

This reminds me too much of WS-* land to be a coincidence. A bunch of  
vendors threw a slew of tools over the wall, wrote a few papers about  
how things *should* be done, but the tools didn't really support  
those lofty thoughts too well. End users got confused and often ended  
up going with what was most familiar (RPC, etc.).

Don't get me wrong -- I think WADL is the bee's knees, and very much  
want to see it succeed. However, looking at the landscape of possible  
ways it could help, and possible ways it could hurt, I'm inclined to  
be conservative -- possibly because I'm very directly accountable for  
the recommendations I make :)

That's why I primarily see it as a modelling tool / convenience for  
design time, rather than something to give to clients. Not because  
those clients will misuse it -- as Marc pointed out earlier, they'll  
always find some way to misuse it -- but because it will lead people  
on the server side into the temptation of relying on it.

Of course, the availability of compelling client-side tools that  
encourage good practice might help convince me otherwise.

Cheers,

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

[Marc Hadley]

On Sep 5, 2006, at 1:12 PM, Mark Nottingham wrote:
>
> Don't get me wrong -- I think WADL is the bee's knees, and very  
> much want to see it succeed. However, looking at the landscape of  
> possible ways it could help, and possible ways it could hurt, I'm  
> inclined to be conservative -- possibly because I'm very directly  
> accountable for the recommendations I make :)
>
It would help those of us in the business of building tools if you  
could list some ways it could hurt so we can avoid them - I have my  
own ideas of course but I'd rather not prejudice your response by  
listing them upfront.

> That's why I primarily see it as a modelling tool / convenience for  
> design time, rather than something to give to clients. Not because  
> those clients will misuse it -- as Marc pointed out earlier,  
> they'll always find some way to misuse it -- but because it will  
> lead people on the server side into the temptation of relying on it.
>
Again, could you give some examples of the harm publishing a WADL  
could do to folks working on the server side ? Given that those same  
folks are responsible for the content of the WADL I'd have thought  
some policy on what is permissible to include in a WADL would be  
sufficient to prevent any anticipated harm.

> Of course, the availability of compelling client-side tools that  
> encourage good practice might help convince me otherwise.
>
As a potential vendor of such tools I'm open to any and all  
suggestions ;-).

Marc.

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

[distobj]

+1, on all counts.

The frustrating thing here from my POV, is that WADL is very nearly a
forms language; consumable at runtime in order to direct a hypermedia
application.  It just needs a few tweaks, as well as to make clear
what's authoritative and what isn't.

Consider the news search example from the spec ...

The "request" stanza is an authoritative description of the parameters
needed to search news, so that's good... though I think it would help
to ground the parameters in URI space to provide a hook for automata
to infer parameters types (as I did with RDF Forms) - as is, it's only
good for human consumption (right back at ya, Sanjiva 8-), unless a
registry of parameter names and associated meanings is presumed (I
assume not).

The "response" stanza is non-authoritative though, because the
response message itself is authoritative.  As Noah discussed, there's
sometimes value in providing this information, but the costs of
counting on it need to be understood.  And as Mark seemed to imply
(and I agree), sometimes it's possible for those costs to exceed the
benefits.  For one, I'd definitely recommend removing schema from
there, as they're notoriously brittle since authors don't typically
account for extensibility  (another major complaint of mine against
WSDL).

The only other thing that WADL would require would be an integration
story; how to embed a WADL document inside documents containing other
languages.  It would imagine it could look something like XForms' - in
fact WADL would be competitive with XForms.

Mark.

On 9/5/06, Mark Nottingham <mnot@...> wrote:

>
> On 2006/09/05, at 5:57 AM, Marc Hadley wrote:
>
> > Personally, even if the above turns out to be the dominant
> > paradigm, I still think there's utility in setting out a map of the
> > available resources and their supported methods and representations
> > and with APP and OpenSearch we already have existence proof that
> > such descriptions are useful. I just hope we can avoid a plethora
> > of such description languages.
>
> Well, *this* Mark agrees. However, as I tried to explain in my
> previous message WRT maps, it's the way that it's used -- on the
> server side as well as client side -- that's important.
>
> This reminds me too much of WS-* land to be a coincidence. A bunch of
> vendors threw a slew of tools over the wall, wrote a few papers about
> how things *should* be done, but the tools didn't really support
> those lofty thoughts too well. End users got confused and often ended
> up going with what was most familiar (RPC, etc.).
>
> Don't get me wrong -- I think WADL is the bee's knees, and very much
> want to see it succeed. However, looking at the landscape of possible
> ways it could help, and possible ways it could hurt, I'm inclined to
> be conservative -- possibly because I'm very directly accountable for
> the recommendations I make :)
>
> That's why I primarily see it as a modelling tool / convenience for
> design time, rather than something to give to clients. Not because
> those clients will misuse it -- as Marc pointed out earlier, they'll
> always find some way to misuse it -- but because it will lead people
> on the server side into the temptation of relying on it.
>
> Of course, the availability of compelling client-side tools that
> encourage good practice might help convince me otherwise.
>
> Cheers,
>
> --
> Mark Nottingham     http://www.mnot.net/
>
>

[Marc Hadley]

On Sep 5, 2006, at 3:35 PM, Mark Baker wrote:
>
> The "request" stanza is an authoritative description of the parameters
> needed to search news, so that's good... though I think it would help
> to ground the parameters in URI space to provide a hook for automata
> to infer parameters types (as I did with RDF Forms) - as is, it's only
> good for human consumption (right back at ya, Sanjiva 8-), unless a
> registry of parameter names and associated meanings is presumed (I
> assume not).
>
Nice idea (grounding parameters in URI space), seems like an ID  
attribute on param would provide the necessary hook.

> The "response" stanza is non-authoritative though, because the
> response message itself is authoritative.  As Noah discussed, there's
> sometimes value in providing this information, but the costs of
> counting on it need to be understood.  And as Mark seemed to imply
> (and I agree), sometimes it's possible for those costs to exceed the
> benefits.  For one, I'd definitely recommend removing schema from
> there, as they're notoriously brittle since authors don't typically
> account for extensibility  (another major complaint of mine against
> WSDL).
>

The "response stanza" is intended to be a list of available  

representations to allow a service to declare what formats are  
available. The example only has a custom XML format but you could  
imagine an Atom feed and JSON also being available.

I agree with the concern about schema (note that the representation/
@element attribute is optional) but I think that should be a decision  
for each service provider rather than something that should be  
prohibited outright. Its quite possible to come up with a versioning  
policy to alleviate such problems.

> The only other thing that WADL would require would be an integration
> story; how to embed a WADL document inside documents containing other
> languages.  It would imagine it could look something like XForms' - in
> fact WADL would be competitive with XForms.
>
Have to think about that but it doesn't look too tricky. WADL uses  
URI refs for inter and intra document references so embedding WADL  
elements in other documents should be quite do-able.

Marc.

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

[Paul Downey]

On 5 Sep 2006, at 20:35, Mark Baker wrote:

>
> +1, on all counts.
>
> The frustrating thing here from my POV, is that WADL is very nearly a
> forms language; consumable at runtime in order to direct a hypermedia
> application.  It just needs a few tweaks, as well as to make clear
> what's authoritative and what isn't.

In many ways both WADL and 'Forms' are the same - they're just
Web pages at the end of a URI describing what you might like
to send to another URI. Actually WADL is better than many HTML
forms in that there likely to be some Javascript magic to subvert the
results - it's all declarative.

I think it's the temporal nature which is the issue here - how long
can you leave between grabbing a WADL (or a HTML form) and then
making GET/POST requests based upon that information?

> Consider the news search example from the spec ...
>
> The "request" stanza is an authoritative description of the parameters
> needed to search news, so that's good...

In many ways the 'authoritative' nature of metadata is an orthogonal  
issue
given there are similar issues for all metadata, including Content-type.
It's tempting to specify a policy for a WADL or a form 'yes, we're  
committed
to supporting this' but then that's just more metadata about, um,  
metadata.

> though I think it would help
> to ground the parameters in URI space to provide a hook for automata
> to infer parameters types (as I did with RDF Forms) - as is, it's only
> good for human consumption (right back at ya, Sanjiva 8-), unless a
> registry of parameter names and associated meanings is presumed (I
> assume not).

Sounds interesting, but I'm having a strong sense of F&P deja-vu!

> The "response" stanza is non-authoritative though, because the
> response message itself is authoritative.  As Noah discussed, there's
> sometimes value in providing this information, but the costs of
> counting on it need to be understood.  And as Mark seemed to imply
> (and I agree), sometimes it's possible for those costs to exceed the
> benefits.  For one, I'd definitely recommend removing schema from
> there, as they're notoriously brittle since authors don't typically
> account for extensibility  (another major complaint of mine against
> WSDL).

Yeah, XML Schema isn't great for *describing* messages. A bag of a
profile of XPath would be my starting point for a message contents
description language.

> The only other thing that WADL would require would be an integration
> story; how to embed a WADL document inside documents containing other
> languages.  It would imagine it could look something like XForms' - in
> fact WADL would be competitive with XForms.

A WADL microformat, even?

--
http://blog.whatfettle.com

[distobj]

On 9/6/06, Paul Downey <paul.downey@...> wrote:
> I think it's the temporal nature which is the issue here - how long
> can you leave between grabbing a WADL (or a HTML form) and then
> making GET/POST requests based upon that information?

Absolutely.  IME, the difference between authoritative and informative
is always time (including latency).

> A WADL microformat, even?

We've already got that; HTML forms 8-)

Mark.

[noah_mendelsohn]

Paul Downey writes:

> On 5 Sep 2006, at 20:35, Mark Baker wrote:
>
> >
> > +1, on all counts.
> >
> > The frustrating thing here from my POV, is that WADL is very nearly a
> > forms language; consumable at runtime in order to direct a hypermedia
> > application.  It just needs a few tweaks, as well as to make clear
> > what's authoritative and what isn't.
>
> In many ways both WADL and 'Forms' are the same - they're just
> Web pages at the end of a URI describing what you might like
> to send to another URI.

The TAG draft finding on metadata in URIs takes that same view of HTML
forms, at least in the example at [1]

I think it's the temporal nature which is the issue here - how long
can you leave between grabbing a WADL (or a HTML form) and then
making GET/POST requests based upon that information?

> I think it's the temporal nature which is the issue here - how long
> can you leave between grabbing a WADL (or a HTML form) and then
> making GET/POST requests based upon that information?

Well, inosfar as cool URI's don't change [2,3], forever. Once that form
goes out from the authority documenting its intended use of a set of URIs,
then in a well run system we can assume that those URIs will continue to
to represent the same resources in perpetuity.  Insofar as the form or
WADL contains hints about the representation, those may become stale, but
we've already said earlier that the representations returned are
authoritative.  It should not be surprising that hints can become stale in
a dynamic system.

> In many ways the 'authoritative' nature of metadata is an orthogonal
> issue given there are similar issues for all metadata, including
> Content-type.  It's tempting to specify a policy for a WADL or a
> form 'yes, we're committed to supporting this' but then that's just
> more metadata about, um, metadata.

The draft TAG finding takes the view that forms and similar documentation
provided by the resource authority are themselves authoritative.So, if I
source from example.org an HTML form that says:  "Type in a city name and
push the button to get the latest National Weather Service data for that
city", and if the form implements the obvious templated URI to generate a
family of URIs using query strings, and crucially if those URIs are
administered by the same authority (example.org), which we can tell from
the DNS addresses, then I have made an authoritative statement about the
purpose of the whole family of URIS.  If those are cool URIs, I've
committed that they will refer to the weather forever.

Converseley, if you send out an HTML form that builds URIs in my domain,
the story is different:  you can't commit me as a URI assigment authority,
unless I have somehow delegated that capability to you.  So, it depends
where the form or WADL comes from, IMO.

Noah

[1] http://www.w3.org/2001/tag/doc/metaDataInURI-31.html#forms
[2] http://www.w3.org/TR/webarch/#URI-persistence
[3] http://www.w3.org/Provider/Style/URI.html

--------------------------------------
Noah Mendelsohn
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------