[rest-practices] Read-only fields in a representation type

[Mark Little]

On 23 Apr 2010, at 13:54, Bryan Kearney wrote:

> On 04/23/2010 08:30 AM, Mark Little wrote:
>> The debate as to whether or not to use WADL isn't tied to HATEOS,  
>> which
>> as you know is only one aspect of REST: the reasons not to use it go
>> much deeper than that. I assume you've checked out various resources
>> like ...
>
> Well.. that is the common refrain. If you are describing the URLs,  
> you _must_ not be using the links, and therefore you are too tightly  
> coupled to the server.

Depends who you listen to. Most of the time I hear WADL mentioned it's  
in the context of how it's not needed at all in RESTful systems.

Here are a few more links you may want to check.

The first covers some important topics that we address in SOA in  
general (REST can be used as the basis for SOA). Specifically some of  
the work we've been doing around Process Governance and contract-first  
designs, are relevant too.

http://service-architecture.blogspot.com/2010/02/why-contracts-are-more-important-than.html

Then everyone should read this. And then read it again.

http://www.w3.org/TR/webarch/

This is an excellent presentation on a real-world RESTful system.

http://www.infoq.com/presentations/restful-financial-systems- 
integration (http://www.slideshare.net/KirkWylie/restful-approaches-to-financial-systems-integration 
) - not a reference to WADL in sight.

And this shows have WSDL 2.0 could be used as a substitute for WADL.  
No, I'm not recommending it, but it's for completeness.

http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/


>
> I find it interesting that the on ramp to rest is "it is simpler",  
> which it is when you go the bookmark approach, and send http  
> requests to known resource locations. If I was asked to write a  
> client against "ThatKoolRestAPI" then either:
>
> 1) The developers had better documented every resource, and every  
> action link which is possible from each link
>
> or
>
> 2) I have to execute each path manually (or with loggin) to see what  
> I can do next.
>
> Since I tend not to trust developers to always update the  
> documentation, it seems like an automated means to do (1) would be  
> valuable to the API writers as well as documenters. Note, I am not  
> advocation IDL driven development. Develop the code, generate the IDL.

This is very similar to what we/I did for quite a few of the later WS- 
* standards, such as WS-TX and WS-RM: develop the on-the-wire messages  
first and then retrofit the WSDL afterwards. Most implementations I  
know still ignore the WSDL these days, with the message format being  
the normative definition. Kind of makes you wonder if the WSDL is  
worth it at all ;-)

>
>
>>
>> http://www.25hoursaday.com/weblog/2007/06/04/WhatsWrongWithWADL.aspx
>> http://stackoverflow.com/questions/1312087/what-is-the-reason-for-using-wadl
>>
>> http://www.markbaker.ca/blog/2007/05/rest-wadl-forest-trees/comment-page-1/
>> http://www.innoq.com/blog/st/2007/06/wadl_just_a_hypermedia_format.html
>> http://www.tbray.org/ongoing/When/200x/2007/05/28/REST
>> http://www.mnot.net/blog/2008/01/21/wadl_watching
>> http://www.infoq.com/news/2007/03/WADL
>
> Some of the these are against it, but much of the haters are in the  
> comments. The best valuable comments are from the fist link which  
> talk about the issues of using XSD as the means to validate. I think  
> these are valid. I would rather see the discussion be around how to  
> make a good descriptor syntax, but it seems to be focused on "why  
> would you ever want to describe your API?"


I think the pragmatic approach that Bill is taking around REST-* is  
right. Maybe there should be a public discussion forum on this within  
the REST-* effort. Bill?

Mark.

---
Mark Little
mlittle at redhat.com

JBoss, by Red Hat
Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod  
Street, Windsor, Berkshire, SI4 1TE, United Kingdom.
Registered in UK and Wales under Company Registration No. 3798903  
Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt  
Parsons (USA) and Brendan Lane (Ireland).