From 7f2ba91cc41132ddbb0cec68ad2c213cb28d856e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 10 Jul 2024 09:37:11 +0200 Subject: [PATCH 1/3] Fix typo: optimistic concurrency _control_ part of link (#1964) --- docs/odata-protocol/odata-protocol.html | 2 +- docs/odata-protocol/odata-protocol.md | 4 ++-- odata-protocol/8 Header Fields.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 23bf75df..cba5a17e 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -1060,7 +1060,7 @@

8.3.2 Header ETag

A response MAY include an ETag header, see RFC9110. Services MUST include this header if they require an ETag to be specified when modifying the resource.

-

Services MUST support specifying the value returned in the ETag header in an If-None-Match header of a subsequent Data Request for the resource. Clients MUST specify the value returned in the ETag header, or star (*), in an If-Match header of a subsequent Data Modification Request or Action Request in order to apply optimistic concurrency control in updating, deleting, or invoking an action bound to the resource.

+

Services MUST support specifying the value returned in the ETag header in an If-None-Match header of a subsequent Data Request for the resource. Clients MUST specify the value returned in the ETag header, or star (*), in an If-Match header of a subsequent Data Modification Request or Action Request in order to apply optimistic concurrency control in updating, deleting, or invoking an action bound to the resource.

As OData allows multiple formats for representing the same structured information, services SHOULD use weak ETags that only depend on the representation-independent entity state. A strong ETag MUST change whenever the representation of an entity changes, so it has to depend on the Content-Type, the Content-Encoding, and potentially other characteristics of the response.

An ETag header MAY also be returned on a metadata document request or service document request to allow the client subsequently to make a conditional request for the metadata or service document. Clients can also compare the value of the ETag header returned from a metadata document request to the metadata ETag returned in a response in order to verify the version of the metadata used to generate that response.

The ETag header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index cdea8128..68970f36 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -1667,8 +1667,8 @@ Request](#RequestingData) for the resource. Clients MUST specify the value returned in the `ETag` header, or star (`*`), in an [`If-Match`](#HeaderIfMatch) header of a subsequent [Data Modification Request](#DataModification) or [Action Request](#Actions) in order to -apply [optimistic concurrency](#UseofETagsforAvoidingUpdateConflicts) -control in updating, deleting, or invoking an action bound to the +apply [optimistic concurrency control](#UseofETagsforAvoidingUpdateConflicts) +in updating, deleting, or invoking an action bound to the resource. As OData allows multiple formats for representing the same structured diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md index 0e926a09..b6a1c2d3 100644 --- a/odata-protocol/8 Header Fields.md +++ b/odata-protocol/8 Header Fields.md @@ -778,8 +778,8 @@ Request](#RequestingData) for the resource. Clients MUST specify the value returned in the `ETag` header, or star (`*`), in an [`If-Match`](#HeaderIfMatch) header of a subsequent [Data Modification Request](#DataModification) or [Action Request](#Actions) in order to -apply [optimistic concurrency](#UseofETagsforAvoidingUpdateConflicts) -control in updating, deleting, or invoking an action bound to the +apply [optimistic concurrency control](#UseofETagsforAvoidingUpdateConflicts) +in updating, deleting, or invoking an action bound to the resource. As OData allows multiple formats for representing the same structured From 2da641661182a1aae81e9b08f8888a616c3d0b8a Mon Sep 17 00:00:00 2001 From: Michael Pizzo Date: Wed, 10 Jul 2024 09:33:58 -0700 Subject: [PATCH 2/3] Clarify rules around continue-on-error (#1966) fixes #1965 1) if any errors are encountered, response MUST include PreferenceApplied with continue-on-error equal to true 2) if any errors are encountered processing a delta request with continue-on-error equal to true, service may either fail the entire request with no changes or return the failures --------- Co-authored-by: Ralf Handl --- docs/odata-protocol/odata-protocol.html | 18 ++++++++++++------ docs/odata-protocol/odata-protocol.md | 6 ++++-- odata-protocol/1 Introduction.md | 1 + odata-protocol/11.4 Data Modification.md | 3 +-- odata-protocol/8 Header Fields.md | 2 ++ 5 files changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index cba5a17e..7789f76f 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -508,31 +508,36 @@

+Section 8.2.8.3 +Responses that include errors MUST include the Preference-Applied header with continue-on-error set to true +1965 + + Section 10.2 Context URLs use parentheses-style keys without percent-encoding 368 - + Section 11.4 Response code 204 No Content after successful data modification if requested response could not be constructed 443 - + Section 11.4.4 Upserts to single-valued non-containment navigation properties 455 - + Section 11.4.9.3 Setting a complex property to a different type 534 - + Section 12 Allow 400 Bad Request in addition to 501 Not Implemented for unsupported functionality 391 - + Section 12.3 Encoding of plus character in URLs 485 @@ -937,6 +942,7 @@

batch request is used to request whether, upon encountering a request within the batch that returns an error, the service return the error for that request and continue processing additional requests within the batch (if specified with an implicit or explicit value of true), or rather stop further processing (if specified with an explicit value of false). The syntax of the continue-on-error preference is defined in OData-ABNF.

The continue-on-error preference can also be used on a delta update, set-based update, or set-based delete to request that the service continue attempting to process changes after receiving an error.

+

If the service encounters any errors processing the request and returns a successful response code, then it MUST include a Preference-Applied response header containing the continue-on-error preference with an explicit value of true.

A service MAY specify support for the continue-on-error preference using an annotation with term Capabilities.BatchContinueOnErrorSupported, see OData-VocCap.

The continue-on-error preference SHOULD NOT be applied to individual requests within a batch.

Note: The continue-on-error preference was named odata.continue-on-error in OData version 4.0. Services that support the continue-on-error preference SHOULD also support odata.continue-on-error for OData 4.0 clients and clients SHOULD use odata.continue-on-error for compatibility with OData 4.0 services.

@@ -2595,7 +2601,7 @@

Core.ContentID term defined in OData-VocCore. Services that respond with 200 OK SHOULD annotate the entities in the response using the same Core.ContentID value as specified in the request.

Services SHOULD advertise support for updating a collection using a delta payload through the DeltaUpdateSupported property of the Capabilities.UpdateRestrictions term, and SHOULD advertise support for returning the Core.ContentID through the ContentIDSupported property of the Capabilities.DeepUpdateSupport term, both defined in OData-VocCap.

The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes.

-

If the continue-on-error preference has been specified and any errors occur in processing the changes, then a delta response MUST be returned regardless of the return preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows:

+

If the client requests continue-on-error behavior and the service encounters any errors while processing the request, then it MUST either fail the entire request without applying any changes or include a Preference-Applied header in the response indicating that the continue-on-error preference has been applied. In this case, the delta response payload MUST be returned regardless of the return preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows: