From 2da641661182a1aae81e9b08f8888a616c3d0b8a Mon Sep 17 00:00:00 2001 From: Michael Pizzo Date: Wed, 10 Jul 2024 09:33:58 -0700 Subject: [PATCH] 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:

  • Failed deletes in the request MUST be represented in the response as either entities or entity references, annotated with the term Core.DataModificationException, see OData-VocCore. If the deleted entity specified a reason of deleted, the value of failedOperation MUST be delete, otherwise unlink.
  • Failed inserts within the request MUST be represented in the response as deleted entities annotated with the term Core.DataModificationException with a failedOperation value of insert.
    • diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 68970f36..c350bd79 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -351,6 +351,7 @@ resource representations that are exchanged using OData. Section | Feature / Change | Issue --------|------------------|------ +[Section 8.2.8.3](#Preferencecontinueonerrorodatacontinueonerror) | Responses that include errors MUST include the Preference-Applied header `with continue-on-error` set to `true` | [1965](https://github.com/oasis-tcs/odata-specs/issues/1965) [Section 10.2](#CollectionofEntities)| Context URLs use parentheses-style keys without percent-encoding| [368](https://github.com/oasis-tcs/odata-specs/issues/368) [Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [443](https://github.com/oasis-tcs/odata-specs/issues/443) [Section 11.4.4](#UpsertanEntity)| Upserts to single-valued non-containment navigation properties| [455](https://github.com/oasis-tcs/odata-specs/issues/455) @@ -1328,6 +1329,8 @@ The `continue-on-error` preference can also be used on a [set-based delete](#DeleteMembersofaCollection) 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`](#HeaderPreferenceApplied) 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`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchContinueOnErrorSupported), @@ -5018,8 +5021,7 @@ term, both defined in [OData-VocCap](#ODataVocCap). 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`](#Preferencecontinueonerrorodatacontinueonerror) preference has been specified and any errors -occur in processing the changes, then a delta response MUST be returned +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`](#HeaderPreferenceApplied) header in the response indicating that the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference has been applied. In this case, the delta response payload MUST be returned regardless of the [`return`](#Preferencereturnrepresentationandreturnminimal) preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows: diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md index 0de95e39..ef36986c 100644 --- a/odata-protocol/1 Introduction.md +++ b/odata-protocol/1 Introduction.md @@ -26,6 +26,7 @@ resource representations that are exchanged using OData. Section | Feature / Change | Issue --------|------------------|------ +[Section ##Preferencecontinueonerrorodatacontinueonerror] | Responses that include errors MUST include the Preference-Applied header `with continue-on-error` set to `true` | [1965](https://github.com/oasis-tcs/odata-specs/issues/1965) [Section ##CollectionofEntities]| Context URLs use parentheses-style keys without percent-encoding| [368](https://github.com/oasis-tcs/odata-specs/issues/368) diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 21dab668..6b97d7fb 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -1043,8 +1043,7 @@ term, both defined in [OData-VocCap](#ODataVocCap). 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`](#Preferencecontinueonerrorodatacontinueonerror) preference has been specified and any errors -occur in processing the changes, then a delta response MUST be returned +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`](#HeaderPreferenceApplied) header in the response indicating that the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference has been applied. In this case, the delta response payload MUST be returned regardless of the [`return`](#Preferencereturnrepresentationandreturnminimal) preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows: diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md index b6a1c2d3..d0db02a8 100644 --- a/odata-protocol/8 Header Fields.md +++ b/odata-protocol/8 Header Fields.md @@ -439,6 +439,8 @@ The `continue-on-error` preference can also be used on a [set-based delete](#DeleteMembersofaCollection) 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`](#HeaderPreferenceApplied) 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`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchContinueOnErrorSupported),