Re: Is it a good idea to make your WADL available?

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

Received on Monday, 4 September 2006 04:00:38 UTC