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

[Bill Burke]

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

I think the difference is that, if documentation is out of sync, that 
the protocol can be hacked by looking at returned responses and data.


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

Well, afaik, there is no tool that can scan both code and XML schema to 
come up with a WADL or similar document that describes application flow. 
  So, you're still gonna have the dependency on the developer to update 
the WADL document or human documentation.

I think this blurb from one of the blogs describes what I mean perfectly:

"And an IDL is simply a list of API signatures. It doesn't describe 
expected message exchange patterns, required authentication methods, 
message traffic limits, quality of service guarantees, or even pre and 
post conditions for the various method calls. You usually find this 
information in the documentation and/or in the actual business contract 
one signed with the Web service provider. A WADL document for the REST 
Web service will not change this fact."

-- 
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com