Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

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.

like image 648
ehdv Avatar asked Dec 12 '13 02:12

ehdv


People also ask

Which is the default HTTP method used to fetch resource using RESTful web service?

As a RESTful API HTTP method, PUT is the most common way to update resource information.

Which of these are the 4 correct types of REST requests?

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.

What does the @GET HTTP method implement in a RESTful API over a collection of Uris?

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


2 Answers

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>
   ....
like image 86
EJK Avatar answered Sep 28 '22 04:09

EJK


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.

like image 34
Matt Ball Avatar answered Sep 28 '22 05:09

Matt Ball