We have a Restful API. In the response of the PUT API, we update the updated timestamp column in the database with the current time and return its value as part "updated" timestamp field in the json response.
My question is if none of the fields in the entity are updated in the PUT call, should the updated timestamp be changed or not?
To elaborate, when performing the same PUT call multiple times, without change in the entity data, should the updated timestamp change?
Are there any best practices?
The HTTP spec specifies that a PUT request should receive a complete representation of the resource and either create it if it doesn't exist (and respond with status 201 Created and empty body), or completely replace it if it does exist (and respond with 200 OK or 204 No Content status and empty body). That's (almost) all. Most APIs of course ignore the "no body should be returned" part.
The "updated" timestamp should not be treated as part of the resource, but rather as metadata about the resource, and updating it should be considered a side-effect of the request, which is out of scope of the spec and so you can treat it however you think is appropriate for your use case.
In my opinion it should NOT be updated because these timestamps are usually used for caching purposes, and since the resource has not been changed there's no reason to invalidate any cache (also keep in mind that PUT requests are not cacheable at all according to the spec). Another use case for the timestamp would be to show final users when the resource last changed, and in that case it would make no sense to update the timestamp if nothing has changed, it would just confuse users.
As an example, Ruby on Rails does not update the updated_at timestamp if no attributes of the model changed.