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

[Bryan Kearney]

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.

-- bk