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.
As a RESTful API HTTP method, PUT is the most common way to update resource information.
The most common are: GET, POST, PUT, and DELETE, but there are several others. There is no limit to the number of methods that can be defined and this allows for future methods to be specified without breaking existing infrastructure. The concept of idempotence is relevant to this discussion.
The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With