feat: add etag and collections

[PavlenkoV]

This update introduces the addition of ETag to collection responses, allowing clients to track versioning for individual resources within a collection. By including an ETag for each item, we enable efficient caching and conditional operations, reducing unnecessary API calls and improving performance. The ETag is added as a read-only field in the response body to ensure version consistency without altering the API's general object model.

This solution can serve as an interim approach until a standardized HATEOAS implementation is adopted.

[omnipitous]

From our convo this morning the above seems great. This line seems redundant.
Search returns a list so Header is invalid and inclusion of ETag in Body makes sense (Response Body *not Request body)
Get By ID: There is only 1 so Header works but having the Etag in both the Header and Body feels redundant.. not the worst thing but can we standardize on 1 instead of both?

[nickclarity]

I agree. But it also feels inconsistent with an ETag being optional in a resource object as part of a collection and required when returned individually.

[travisgosselin]

To me its similar reasoning to including the status code in the body of error message (impacts logging, convenience, etc). In this case specifically, its the intersection of two patterns, where we want data model consistency between your resources returned in collection or singular, but also consistency to other resources by id that use ETag as the more industry norm pattern for individual results.

I think for consistency, both are necessary depending on how the consumer will make use of it.

[nickclarity]

That makes sense. I can see why we wouldn't want multiple schema's to represent the same thing and/or context specific schemas.

[travisgosselin]

@omnipitous / @nickclarity / @PavlenkoV - I appreciate your expertise, effort, and review on this one.