From c22e082035a5c980587b278a668f1914cabd87fc Mon Sep 17 00:00:00 2001 From: Travis Gosselin Date: Mon, 9 Sep 2024 13:28:36 -0400 Subject: [PATCH] Update standards/collections.md Co-authored-by: Nick Clarity <61919291+nickclarity@users.noreply.github.com> Signed-off-by: Travis Gosselin --- standards/collections.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standards/collections.md b/standards/collections.md index f99a7aa..70bbcac 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 reach 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. 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` **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.