Skip to content

Commit

Permalink
Update standards/collections.md
Browse files Browse the repository at this point in the history
Co-authored-by: Nick Clarity <[email protected]>
Signed-off-by: Travis Gosselin <[email protected]>
  • Loading branch information
travisgosselin and nickclarity authored Sep 9, 2024
1 parent 2295901 commit c22e082
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion standards/collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit c22e082

Please sign in to comment.