How should a RESTful service expose read-only properties on mutable resources?

Question

I am working on designing a resource for this service which has a set of mutable properties and a set of immutable ones (for example, status which is generated by the service and not something the client may change).

I need to include this in responses to GET requests for the resource but am not sure what to do if someone then sends the resource with a PUT request.

Forcing the caller to know which properties are immutable feels wrong, but silently discarding updates also feels incorrect. Responding with the updated resource to the PUT request might solve the issue, but it's imperfect since the caller shouldn't have to do a diff of its request and the service's response to find out if a property was accepted.

Any thoughts on the right way forward?

P.S. I looked at How should I update a REST resource? but it's different from this question and promotes an overly-chatty API design.

Answer 1

I would suggest following the guidelines at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10. The definition of HTTP 409 includes the following:

1) The request could not be completed due to a conflict with the current state of the resource.

2) The response body SHOULD include enough information for the user to recognize the source of the conflict.

Thus as changes to immutable properties are a problem with the state of the resource, HTTP 409 seems to apply.

As for how to communicate the issue to the client, the guidance seems to be to include details in the response body.

You could also communicate mutability of properties in the representation itself (on the GET). For example.

<MyObject>
   <Foo>17</Foo>
   <Bar readOnly="true">22</Bar>
   ....

Answer 2

You could design your API's responses so that the read-only properties are actually separate from the mutable ones. For example:

{
    id: 42,
    status: "terrific",
    properties: {
        // mutable properties here
    }
}

I have both written and consumed APIs that do this, and it's worked out just fine.

Answer 3

Use HTTP PATCH with JSON-Patch documents - this allows you to pin-point exactly the properties you want to modify. See https://www.rfc-editor.org/rfc/rfc6902.

But there is nothing wrong about PUT'ing both immutable and mutable elements back. The server is free to ignore what ever it doesn't want to make changes to. I wrote an in-depth discussion on this topic here: http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html

Answer 4

Another solution is to send the read-only fields back as HTTP headers. That way you can keep the GET and PUT resources identical.

This probably makes most sense if the read-only fields are primarily "technical" fields such as createTime, updateTime, etc. Status could be regarded as a technical field as well ?