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

[Bill Burke]

Bill Burke wrote:
> 
> 
> Bryan Kearney wrote:
>> On 04/21/2010 09:20 AM, Bill Burke wrote:
>>>
>>>
>>> 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.
>>>
>>>
>> In my experience, developers will forget to update it. I would prefer 
>> to auto generate it off of the code.
>>
> 
> Good point.  A resteasy committer has written a jaxrs-javadoc generator. 
>  Of course this wouldn't work very well with non-java implementations. 
>  Jersey has nice support for WADL.  Wouldn't be hurt if you decided to 
> move to it because of WADL.  I just don't have the time or will to get 
> into any WADL development/support.
> 
> While WADL does support the concept of linking and opaque URLs, it 
> doesn't contrain itself.  I worry that with WADL you'll get a tighter 
> coupling between client-server that isn't desired.
> 

BTW, I'm not sure Jersey's WADL support is gonna support automated link 
introspection and you'll still have the "forgetting to update" problem.

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