diff --git a/standards/collections.md b/standards/collections.md index 70bbcac..0c42e78 100644 --- a/standards/collections.md +++ b/standards/collections.md @@ -633,7 +633,7 @@ ETags in consideration with resource collections post some additional considerat - `ETags` used in a response header **MUST** represent the entire of the response body, which is the entire collection rather than an individual resource. This is typically less useful in many situations. Working with paged collection results means the response header `ETag` is page-sensitive. - `ETags` on a collection resource **MAY** exist both for the entire response body as a response header, and as an individual `ETag` property on each resource item in the response body if needed. -- `ETags` are best represented as metadata in headers, agnostic or separated from the resource model representation. However, some requests to resource collections may benefit from including an `ETag` with each resource individual resource represented in the collection. Adding an `ETag` to the body of a collection response can help reduce the number of API calls by allowing clients to track changes to individual resources without needing to fetch each resource one by one. The `ETag` will act as a unique identifier for each resource version, ensuring that clients can perform safe and efficient updates or deletions without conflicts with `If-Match` header. If using granular collection `ETags` in the response body, then: +- `ETags` are best represented as metadata in headers, agnostic, or separated from the resource model representation. However, some requests to resource collections may benefit from including an `ETag` with each resource individual resource represented in the collection. Adding an `ETag` to the body of a collection response can help reduce the number of API calls by allowing clients to track changes to individual resources without needing to fetch each resource one by one to make use of request headers like `If-Match`. If using granular collection `ETags` in the response body, then: - `ETags` **SHOULD** be added to the object model for the response body as a read-only field as a sibling to the `id` of each result item. - `ETag` response header **MUST** be present when retrieving an individual resource. - `ETag` property in the response body **MUST** also be present for retrieving an individual resource.