Skip to content

Commit

Permalink
indicate page sensitivity to collection level etags.
Browse files Browse the repository at this point in the history
  • Loading branch information
travisgosselin committed Sep 9, 2024
1 parent 52e0beb commit 2295901
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 @@ -631,7 +631,7 @@ DELETE /articles?ordering=title // ordering only app

ETags in consideration with resource collections post some additional considerations on what the `ETag` should represent and in what granularity. For more general details about using `ETags` in request and response headers for optimistic concurrency, see the [Request Response](request-response.md#etag) section. When working with ETags in collections, the following considerations should be taken into account:

- `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.
- `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` **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.
Expand Down

0 comments on commit 2295901

Please sign in to comment.