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

[Bryan Kearney]

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.

As to your solution, I would think with versioning that you would want 
to fail silently. If the client sends more data to a back-reved server 
it may be nice to have it still work.

-- bk