ETags and a Persisted Version Reference for An Object

[travisgosselin]

From: @GordyRaup

Related: https://atlassian.spscommerce.com/wiki/pages/viewpage.action?pageId=331998946#APIRequest&Response-GET

I've never used ETags before, but reading the documentation you've included, it is addressing the same concern as I had.
However, I'd recommend either making a change to the guidance or at least mentioning the following issue: In practice, to be reliable, the version reference needs to be persisted with the object it references so that the DB can do the checking/rejecting. In which case, why would we remove the version attribute from what is returned to the caller in the object. I have no problem duplicating it in the ETag and If-Match headers if needed to maintain compliance with API standards, but why create more work for both ourselves and our clients by not including the version attribute in the object itself. If we remove it from the object before returning the response, then the client app has to either separately store the ETag or add it back into the object before persisting it on their side so that they have it available when the user decides to make a change. Similarly, when we receive the ETag in a PUT, or PATCH request, we would have to add it back into the object before persisting it so that the DB check could catch any discrepancy. Why create all that extra work on both sides? Wouldn't it be better to just leave the version attribute in the object definition in the first place? If you need to put the value in the header as well, that's okay, but leave it in the object first and foremost.

Of course, if you agree with my logic here, why put the version attribute into the header at all if it is providing no additional value. Or, is there additional value to duplicating the version attribute in the header using ETag/If-Match headers? If so, what is that additional value?

[travisgosselin]

Good question! ETags are relatively new to myself as well, but found that they made a lot of sense for dealing with concurrency. While I appreciate your perspective, I think that you'll find to produce a GREAT RESTful API following many of the best practices there is often more manipulation and transformation needed at the contract layer to the API than perhaps SPS has done in the past (I'm thinking about paging, sorting, filtering contracts, etc). That being said, I think you can appreciate that your concern is largely based on leaking of your implementation. Because the version exists in your data model it does make it easy for you to provide on the object returned by defualt, but that would not be true for other implementations using the opaque ETag version value from a different location or even dynamically generated (lets say as a hash of the contents of the object).

Additionally, the usage of ETag headers for concurrency is not an invention of SPS but rather a standard header and pattern used. As a result the goals of the REST API Standards are intended to encourage and foster industry level standards, which can be inherently understand across not just our APIs but others as well, without individuals have to understand specifically where to pull version information from your custom data model and how to use it. Making use of ETags, If-None-Match headers, etc provide immediate understanding across industry's and organizations to the intent and usage of your API (in this case for versioning of the resource).

You will also find that there are other more technical benefits to ETags (though it may not be used directly in our infrastructure today) such as detecting and caching resources (without having to deserialize the body - which may be done by some clients as well). A few well put paragraph's here too: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag