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

[Bill Burke]

Bryan Kearney wrote:
> On 04/20/2010 03:32 PM, Mark McLoughlin wrote:
>> On Tue, 2010-04-20 at 15:22 +0100, Eoghan Glynn wrote:
>>
>>> Folks,
>>>
>>> A REST design question ... suppose we're using the same representation
>>> in a number of different contexts:
>>>
>>> 1. to capture client input to resource creation (i.e. the payload in the
>>> POST /collection request)
>>>
>>> 2. to encode a state change initiated by the client (i.e. the payload
>>> for the PUT /collection/id request)
>>>
>>> 3. to represent the complete resource state sent back to the client
>>> (i.e. response to GET /collection/id)
>>>
>>> Say the representations used in cases #1 and #2 are a proper subset of
>>> #3, because some of the fields must be computed, or have fixed
>>> defaults/initial values. So the question is, how do we enforce this
>>> constraint?
>>>
>>> We could define separate types to ensure that only those fields that
>>> really can be set by the client are used in the POST and PUT, and then
>>> enforce via schema validation or whatever.
>>>
>>> Or is best to be tolerant and just silently discard any read-only fields
>>> specified in the first two cases?
>>
>> (We discussed already, but for the benefit of discussion here)
>>
>> For simplicity sake, I think it makes sense to stick with the same
>> representation.
>>
>> Rather than silently discard read-only fields, though, I'd prefer us to
>> return an error. That way the semantics are clear.
>>
>> It'd be nice if this was easy to do with JAX-B/JAX-RS, but it doesn't
>> seem to be.
> 
> 
> This is one reason where I think a WADL type tool would be nice. I do 
> not want to use WADL to define my services, but I would like some 
> description of them to give to clients to say "If you do this, it will 
> work". The argument of not using wadl because of HATEOAS does not fly to 
> well.. since we should be able to encode the link names.
> 

Or, you could just write a document that said "If you do this, it will 
work...", put it on a searchable wiki.  Reference the page within schema 
URLs and link relationship urls, etc.


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