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

Bill Burke bburke at redhat.com
Wed Apr 21 15:14:11 UTC 2010



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.

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




More information about the rest-practices mailing list