From 34c01a26281f688b473fece6ba53887c4ea147be Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 5 Sep 2024 16:41:46 +0200 Subject: [PATCH] Align if-match * and if-none-match * with RFC9110 --- docs/odata-protocol/odata-protocol.html | 8 ++++---- docs/odata-protocol/odata-protocol.md | 14 ++++++++------ odata-protocol/8 Header Fields.md | 14 ++++++++------ 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index ba4042aa..ba7039e4 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -926,11 +926,11 @@

8.2.4 Header If-Match

-

As defined in RFC9110, a client MAY include an If-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-Match request header MUST be an ETag value previously retrieved for the resource, or * to match any value.

-

If an operation on an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.

+

As defined in RFC9110, a client MAY include an If-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-Match request header MUST be an ETag value previously retrieved for the resource, or *.

+

If modification of an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.

If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending ETag headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from RFC9110.

If the value does not match the current ETag value of the resource for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request. In the case of an upsert, if the addressed entity does not exist the provided ETag value is considered not to match.

-

An If-Match header with a value of * in a PUT or PATCH request results in an upsert request being processed as an update and not an insert.

+

An If-Match header with a value of * matches any current representation of the resource, and in a PUT or PATCH request results in an upsert request being processed as an update and not an insert, independent of whether the resource requires an ETag.

The If-Match header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.

@@ -938,7 +938,7 @@

RFC9110, a client MAY include an If-None-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-None-Match request header MUST be an ETag value previously retrieved for the resource, or *.

If present, the request MUST only be processed if the specified ETag value does not match the current ETag value of the resource, using the weak comparison function (see RFC9110). If the value matches the current ETag value of the resource, then for a GET request, the service SHOULD respond with 304 Not Modified, and for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request.

-

An If-None-Match header with a value of * in a PUT or PATCH request results in an upsert request being processed as an insert and not an update.

+

An If-None-Match header with a value of * “matches” if there is no current representation of the resource, and in a PUT or PATCH request results in an upsert request being processed as an insert and not an update, independent of whether the resource requires an ETag.

The If-None-Match header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 2dc6bc04..d05e9604 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -1061,9 +1061,9 @@ batch request. As defined in [RFC9110](#rfc9110), a client MAY include an `If-Match` header in a request to `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. The value of the `If-Match` request header MUST be an ETag -value previously retrieved for the resource, or `*` to match any value. +value previously retrieved for the resource, or `*`. -If an operation on an existing resource requires an ETag, (see term +If modification of an existing resource requires an ETag, (see term [`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in [OData-VocCore](#ODataVocCore) and property `OptimisticConcurrencyControl` of type @@ -1090,9 +1090,10 @@ ensure that no observable change occurs as a result of the request. In the case of an [upsert](#UpsertanEntity), if the addressed entity does not exist the provided ETag value is considered not to match. -An `If-Match` header with a value of `*` in a `PUT` or `PATCH` request +An `If-Match` header with a value of `*` matches any current representation of the resource, and in a `PUT` or `PATCH` request results in an [upsert request](#UpsertanEntity) being processed as an -update and not an insert. +[update](#UpdateanEntity) and not an [insert](#CreateanEntity), +independent of whether the resource requires an ETag. The `If-Match` header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch. @@ -1115,9 +1116,10 @@ the service MUST respond with [`412 Precondition Failed`](#ResponseCode412PreconditionFailed) and MUST ensure that no observable change occurs as a result of the request. -An `If-None-Match` header with a value of `*` in a `PUT` or `PATCH` +An `If-None-Match` header with a value of `*` "matches" if there is no current representation of the resource, and in a `PUT` or `PATCH` request results in an [upsert request](#UpsertanEntity) being processed -as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity). +as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity), +independent of whether the resource requires an ETag. The `If-None-Match` header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch. diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md index d0db02a8..3dcd75ee 100644 --- a/odata-protocol/8 Header Fields.md +++ b/odata-protocol/8 Header Fields.md @@ -164,9 +164,9 @@ batch request. As defined in [RFC9110](#rfc9110), a client MAY include an `If-Match` header in a request to `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. The value of the `If-Match` request header MUST be an ETag -value previously retrieved for the resource, or `*` to match any value. +value previously retrieved for the resource, or `*`. -If an operation on an existing resource requires an ETag, (see term +If modification of an existing resource requires an ETag, (see term [`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in [OData-VocCore](#ODataVocCore) and property `OptimisticConcurrencyControl` of type @@ -193,9 +193,10 @@ ensure that no observable change occurs as a result of the request. In the case of an [upsert](#UpsertanEntity), if the addressed entity does not exist the provided ETag value is considered not to match. -An `If-Match` header with a value of `*` in a `PUT` or `PATCH` request +An `If-Match` header with a value of `*` matches any current representation of the resource, and in a `PUT` or `PATCH` request results in an [upsert request](#UpsertanEntity) being processed as an -update and not an insert. +[update](#UpdateanEntity) and not an [insert](#CreateanEntity), +independent of whether the resource requires an ETag. The `If-Match` header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch. @@ -218,9 +219,10 @@ the service MUST respond with [`412 Precondition Failed`](#ResponseCode412PreconditionFailed) and MUST ensure that no observable change occurs as a result of the request. -An `If-None-Match` header with a value of `*` in a `PUT` or `PATCH` +An `If-None-Match` header with a value of `*` "matches" if there is no current representation of the resource, and in a `PUT` or `PATCH` request results in an [upsert request](#UpsertanEntity) being processed -as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity). +as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity), +independent of whether the resource requires an ETag. The `If-None-Match` header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.