REST get calculated view of resource - rest

Question

I'm interested in the correct convention to use when requesting a calculation on an entity from the server. That is - a specific entity is involved, but its data is not returned. Instead, a calculation based on the entity is returned.
Take for example a site that stores multiple clocks, each with a different offset/timezone value. The purpose of the site is to present images of analog clocks with hands pointing in the appropriate direction.
Using good convention I would expect to be able to do this:
POST /clocks
{
"offsetHours": 5
}
And I would receive this response:
201 (Created)
{
"id": "fe884d5e",
"offsetHours": 5
}
Now I would expect to be able to retrieve that clock object:
GET /clocks/fe884d5e
Which responds:
200 (OK)
{
"id": "fe884d5e",
"offsetHours": 5
}
This is all fine so far. But there are two other endpoints I would expect to have access to. The first one would return the current time calculated for a clock's offset. The second one would return image data displaying an analog clock based on the clock's current time.
My question is: what does convention dictate the GET requests for these data items should look like? Or is convention loose when it comes to dealing with calculated views of entities?

Answer 1

But there are two other endpoints I would expect to have access to. The first one would return the current time calculated for a clock's offset.
Something like
GET /clocks/fe884d53/localTime
The second one would return image data displaying an analog clock based on the clock's current time.
Something like
GET /clocks/fe884d5e/localTime/analogClock.jpg
or
GET /clocks/fe884d5e/analogClock.jpg
The key idea here is that these are information resources, in precisely the same way that the description of the clock itself is an information resource.
From the point of view of the consumer, the representation is just a document. There shouldn't be any way to know if the document was freshly generated, or copied from a document store, or pulled out of a web cache.
The fact that there is a calculation is just an implementation hidden behind the api.
Once you have clear the idea that these are different resources that share implementation details, the remainder of the work is just bike shedding (is it easy for our routing to find the right implementation? do we have the hierarchical data in the path segment, and the non hierarchical parts in the query, does the spelling look enough like a "resource" to conform with our local coding standards, etc).