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

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


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>
   ....

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.


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 ?