REST API design: Tell the server to "refresh" a set of resources

Question

We have some resources on a REST server structured like this:

• /someResources/foo
• /someResources/bar
• /someResources/baz

where someResource is a server representation of a distributed object far away.

We want to tell the server to "refresh" its representation of that "distributed object" by looking at it out in the network & updating the server's cache i.e. we can not simply PUT the new value.

What is the clean REST way to this ?

a) Is it to POST to a /refreshes/ a new "refresh request" ?

b) Is it to PUT (with a blank document) to http://ip/someResources ?

c) Something else ?

I like (a) as it will give us an id to identify & track the refresh command but worried that we are creating too many resources. Any advice?

Answer 1

I would go with the 'refreshes' resource approach. This has two major benefits

(a) Like life-cycle operations (copy, clone, move) the purpose of the refresh is orthogonal to the function of the underlying resource so should be completely separate

(b) It gives you some way of checking the progress of the refresh - the external state of the refresh resource would provide you with a 'status' or 'progress' attribute.

We've implemented the life-cycle operations this way and the separation of concerns is a big design plus.

A better approach

Another way to manage this is to allow the server to cache it's representation of the resource for some period of time, only actually checking the real state after some timeout. In this model your server is really an intermediate caching resource and should follow the HTTP Caching behaviour see here for more details. Below I quote a very relevant section which talks about the client overriding the cached values.

13.1.6 Client-controlled Behavior While the origin server (and to a lesser extent, intermediate caches, by their contribution to the age of a response) are the primary source of expiration information, in some cases the client might need to control a cache's decision about whether to return a cached response without validating it. Clients do this using several directives of the Cache-Control header.

A client's request MAY specify the maximum age it is willing to accept of an unvalidated response; specifying a value of zero forces the cache(s) to revalidate all responses. A client MAY also specify the minimum time remaining before a response expires. Both of these options increase constraints on the behavior of caches, and so cannot further relax the cache's approximation of semantic transparency.

A client MAY also specify that it will accept stale responses, up to some maximum amount of staleness. This loosens the constraints on the caches, and so might violate the origin server's specified constraints on semantic transparency, but might be necessary to support disconnected operation, or high availability in the face of poor connectivity.

Chris