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

[David Lutterkort]

On Tue, 2010-04-20 at 20:32 +0100, 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.

That's kinda the opposite of what we expect from clients - for those, we
want them to pick out what they know about, and ignore the rest. As long
as what they send is unambiguous, I don't see the harm in ignoring
read-only fields.

This whole discussion is really caused by the paucity of API/schema
documentation tools. In an ideal world, we could have one schema for
each object, and indicate which parts of the schema are relevant for
what operations.

David