Re: Caveats for Web-friendly service description

On Jun 1, 2005, at 4:23 AM, Mark Baker wrote:
>
> Both WDL and WADL (and perhaps others, I just happened to notice these
> two did it) declare the list of possible response codes that a service
> returns, ala;
>
> WDL: <wdl:output code="400 403 503" ref="yahoosrch:Error"/>
>
> WADL: <wadl:fault name="searchError" status="400 403 503"/>
>
> I don't think that's a very good idea, because if those  
> descriptions are
> used to generate client code, then that code will be inconsistent with
> the HTTP spec since it says;
>
>   "applications MUST understand the class of any status code, as
>    indicated by the first digit, and treat any unrecognized  
> response as
>    being equivalent to the x00 status code of that class"
>     -- http://www.zvon.org/tmRFC/RFC2616/Output/chapter6.html#sub1
>
> (Alternately, if those status codes aren't used to generate code, then
> what are they used for?  That's why I believe they should go.)
>
In WADL the fault elements are intended to specify an inclusive  
rather than exclusive list. Listing a set of faults doesn't preclude  
use of any other HTTP status code. The fault elements allow code  
generation for the set of specific conditions listed in the  
description. Other conditions can be handled in some more generic  
fashion. E.g. use of fault allows generated code to support error  
handling like:

try {
   // some operation
}
catch {SearchException s) {
   // some search error specific error handling
}
catch {HTTPProtocolException e) {
   // some generic exception handling
}

Without faults you'd only be able to use the generic exception and  
then have to go digging in that to work out what went wrong.

> The general point here, is, I believe, not that we have to be careful
> with violating any specs (though of course that's still important),  
> but
> instead that we avoid, for the cases where code will be generated,
> describing things which may change in the foreseeable future.  The
> reason is simply that we should be aiming for loose coupling, and  
> having
> a change in a service (e.g. new response code) require a change in a
> client works directly against that.
>
Agreed, I think the inclusive vs exclusive nature of faults  
accomplishes this.

> Another example of this is the use, in most of the description specs
> I've seen, of XML schema.  For the same reason as above, I generally
> think it's a bad idea to describe the data produced using a schema
> since schemas generally (DaveO's excellent extensibility advice
> notwithstanding) change foreseeably over time, and I don't want a  
> change
> in the schema produced by a service breaking clients if I can help it.
> Instead, I'm more a fan of simply using a media type as a name for an
> open-ended sequence of backwards-compatible schemas (think "text/html"
> vs. HTML 2.0, 3.2, 4.01, etc..), as well as, of course, associating an
> extensible processing model to that media type to accomodate as many
> unanticipated extensions as possible over time.
>
Paul Downey and I discussed this over a few beers last night. I think  
there's a tension between providing a loose description that is more  
open to evolution but less useful in terms of code generation and a  
description that is tighter but more useful for code generation. WADL  
parameters are a nod in this direction, if the representation is  
relatively simple and the description includes parameters then the  
schema can be ignored when processing a received representation (you  
just apply the XPaths and grab the information you're interested in).  
However in order to produce a document you need access to something  
that describes the format you're expected to produce in some detail.

Marc.

> So what does such advice mean to a description language?  IMO, it  
> means
> that we should be designing a forms language, not what is typically
> known to be a "service description language".  A forms language is
> processed entirely at runtime, and declares state transitions,  
> possibly
> parameterized, of an application.  RDF Forms is a forms language.   
> WRDL
> is another.  WSDL 2.0 has some form features, but is predominantly for
> service description.
>
> It would be good to see some other views of what it is exactly that
> we're trying to accomplish here, i.e. what aspects of a service should
> a standard description language describe or not describe?
>
> Cheers,
>
> Mark.
> -- 
> Mark Baker.  Ottawa, Ontario, CANADA.          http://www.markbaker.ca
> Coactus; Web-inspired integration strategies   http://www.coactus.com
>
>

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