As an application developer I only want to load the updated data from Wikibase instance, so I can update it in my app only when data changes
See `If-None-Match` and `If-Modified-Since` parameters in the specification: https://gerrit.wikimedia.org/r/773447
**BDD**
As an API user
GIVEN there is a newer and different version of item data than revision ID N
WHEN I make a GET request to /entities/items/{item_id}
AND I provide N as the revision ID in `If-None-Match` header
THEN I receive 200 HTTP response from the API
AND response contains item data
AND response headers contain the item metadata as indicated in the specs
As an API user
GIVEN The most recent version of an item is N
WHEN I make a GET request to /entities/items/{item_id}
AND I provide N as the revision ID in `If-None-Match` header
THEN I receive 304 HTTP response from the API
(weak comparison)
As an API user
GIVEN The most recent version of an item is N
AND past revision M contains the same data as revision N
WHEN I make a GET request to /entities/items/{item_id}
AND I provide M as the revision ID in `If-None-Match` header
THEN I receive 304 HTTP response from the API
(edge case, `*` only makes sense in conditional PUT requests)
WHEN I make a GET request to /entities/items/{item_id}
AND I provide `"*"` as the revision ID in `If-None-Match` header
THEN I receive 200 HTTP response from the API
AND response contains item data
AND response headers contain the item metadata as indicated in the specs
As an API user
GIVEN there is a newer version of item data than published on or before the timestamp Y
WHEN I make a GET request to /entities/items/{item_id}
AND I provide Y as a timestamp in `If-Modified-Since` header
THEN I receive 200 HTTP response from the API
AND response contains item data
AND response headers contain the item metadata as indicated in the specs
As an API user
GIVEN The most recent version of an item is the version published on or before the timestamp Y
WHEN I make a GET request to /entities/items/{item_id}
AND I provide Y as a timestamp in `If-Modified-Since` header
THEN I receive 304 HTTP response from the API
**Note:**
- Per [RFC 7232](https://datatracker.ietf.org/doc/html/rfc7232#section-3.2) versions of an item defined by revision IDs provided in If-None-Match are to be compared using the [weak comparison](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests#weak_validation).
- `If-None-Match` accepts multiple ETags/Revision IDs. If any of them is the most recent version of the item (in weak comparison sense), the API should return 304 response
- As only weak comparison is relevant for `If-None-Match`, ETags of both formats 123 and W/"123" are considered synonyms
- timestamps must be HTTP dates as defined in [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.1.1) (see also [date syntax](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since#syntax), [HttpDate](https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/refs/heads/master/includes/Rest/HeaderParser/HttpDate.php) class in Mediawiki REST API). Invalid dates are to be ignored - without returning errors to the client.
- revision IDs/ETags which are not valid revisions IDs (e.g. not numbers), or are not actual revisions of the request item are to be ignored - without returning any errors to the client
- if both `If-None-Match` and `If-Modfied-Since`, `If-None-Match` will be considered and `If-Modified-Since` ignored
- ~~weak comparison of ETags is out of scope of this story, and will be handled separately: T304832~~
**"Weak" comparison of Item versions/revisions**
- two revisions of an Item are considered identical if they contain the same item data (ID, labels, descriptions, aliases, statements and sitelinks) identical. Metadata like date of the revision is ignored
- Statements are considers equal if their whole structure is the same (i.e. including GUIDs)
- in other words, in weak comparison items are considered equal if the "diff" between their json structures is the same