BB-24252: Create new API endpoint for recalculating order prices during order editing/creation (#39224)

- added new backend ordersubtotals resource
- added an orderSubtotals relation to orders endpoint
- added meta validate operation flag
- added enable_validation entity api config option
- added new rollback_validated_request event for customize_form_data action
- updated add orderSubtotals logic for create and update api actions
- added new --validate option for oro:api:dump command
- added validate operation description for matched API resources
- added reuse of an existing entity for response to the validated operation
- updated orderSubtotals field collapse logic for the orders resource

---------

Co-authored-by: Daria Hanzenko <[email protected]>
Co-authored-by: Yefim Yevtushenko <[email protected]>
Co-authored-by: Kateryna Isakova <[email protected]>
Co-authored-by: Yefim Yevtushenko <[email protected]>

Author: 4 people

api/index.rst

@@ -49,6 +49,7 @@ Find more information about Web API in the following topics:
    filters
    create-update-related-resources
    upsert-operation
+   validate-operation
    client-requirements
    batch-api
    sync-batch-api

api/validate-operation.rst

@@ -0,0 +1,92 @@
+.. _web-services-api--validate-operation:
+
+Validating a Resource
+=====================
+
+When creating or updating a primary API resource, you may need to validate it without persisting.
+
+The validation is triggered in the |JSON:API: Meta Section| section via the "validate" option set to ``true``. The validation operation is supported by POST and PATCH requests.
+
+How to Enable
+-------------
+
+Resource that supports a validation should be marked with `enable_validation` flag in api.yml:
+
+.. code-block:: yaml
+   :caption: config/api.yml
+
+    api:
+        // ... skipped
+        entities:
+            Oro\Bundle\OrderBundle\Entity\Order:
+                documentation_resource: '@OroOrderBundle/Resources/doc/api/order.md'
+                enable_validation: true # Enables validation operation
+        // ... skipped
+
+Then such resource would also contain the corresponding note in the API Sandbox. For example:
+
+.. image:: /img/backend/api/validate_operation_note.png
+   :alt: An example of the validate operation note
+
+Implementation Details
+----------------------
+
+Unlike the regular create or update action, the `validate` meta flag forces a database transaction rollback in the ``\Oro\Bundle\ApiBundle\Processor\CustomizeFormData\FlushDataHandler``. Keep in mind that the rollback also prevents asynchronous operations (e.g., those triggered by a message in MQ), including search reindexing, sending emails, etc. However, it cannot instantly reverse actions that have already been completed during the processing of an API request (for example, if a file is deleted in one of the API processors). Therefore, if you enable validation on an entity, you need to ensure that no irreversible operations are being carried out during the creation and update actions for that entity. If there are, it is important to either delay or make these operations asynchronous where possible.
+
+Examples
+--------
+
+An example of a POST validate requests:
+
+**Request**
+
+.. code-block:: http
+
+    POST /api/orders HTTP/1.1
+    Content-Type: application/vnd.api+json
+    Accept: application/vnd.api+json
+
+**Request Body**
+
+.. code-block:: json
+
+    {"data": {
+        "type": "orders",
+        "meta": {
+          "validate": true
+        },
+        "attributes": {
+          "identifier": "FR1012401Z",
+          "poNumber": "CV032342USDD",
+        }
+      }
+    }
+
+An example of a PATCH validate requests:
+
+**Request**
+
+.. code-block:: http
+
+    PATCH /api/orders/1 HTTP/1.1
+    Content-Type: application/vnd.api+json
+    Accept: application/vnd.api+json
+
+**Request Body**
+
+.. code-block:: json
+
+    {"data": {
+        "type": "orders",
+        "id": "1",
+        "meta": {
+          "validate": true
+        },
+        "attributes": {
+          "customerNotes": "Please, call before delivery"
+        }
+      }
+    }
+
+.. include:: /include/include-links-dev.rst
+   :start-after: begin

backend/api/actions.rst

@@ -885,6 +885,7 @@ This action is executed when the following |ApiEvents| are dispatched:
     "pre_flush_data","This event is dispatched after the database transaction is open but before data are flushed into the database. Do not call EntityManager::persist() and EntityManager::remove() during handling of this event, use addAdditionalEntity() and addAdditionalEntityToRemove() methods of the context instead."
     "post_flush_data","This event is dispatched after data are successfully flushed into the database but before the database transaction is committed."
     "post_save_data","This event is dispatched after data are successfully flushed into the database, and the database transaction is committed. It can be used to perform some not crucial operations after data are saved into the database. It means that failure of these operations will not roll back data saved into the database."
+    "rollback_validated_request","This event is dispatched before the database transaction is rolled back for API requests with a meta `validate` operation flag."
 
 .. note:: All these events use the same context, so it can be used to share data between events.
 

backend/api/commands.rst

@@ -165,6 +165,12 @@ To get all entities that support :ref:`the upsert operation <web-services-api--u
 
     php bin/console oro:api:dump --upsert
 
+To get all entities that support :ref:`the validate operation <web-services-api--validate-operation>`, use the ``--validate`` option:
+
+.. code-block:: none
+
+    php bin/console oro:api:dump --validate
+
 .. _oroapidebug:
 
 oro:api:debug

backend/api/configuration.rst

@@ -222,6 +222,8 @@ The ``entities`` section describes the configuration of entities.
 
 *  **disable\_partial\_load** *boolean* - The flag indicates whether using of |Doctrine partial objects| is disabled. By default ``false``. When using partial objects, the ``HINT_FORCE_PARTIAL_LOAD`` query hint is used together with them to avoid loading unneeded foreign keys.
 
+*  **enable\_validation** *boolean* - The flag indicates whether it is possible to use a `validate` meta flag on create and update actions. By default ``false``. When the value is ``true``, API requests with a `validate` meta flag make transaction rollback instead of commit. Please be advised that enabling this option will also roll back other component operations, such as sending a mail or triggering a search reindex.For details, see :ref:`Configure Validate Operation <configure-validate-operation>`.
+
 *  **hints** *array* - The |Doctrine query hints|. Each item can be a string or an array with ``name`` and ``value`` keys. The string value is a short form of ``[name: hint name]``.
 
 *  **inner\_join\_associations** *string[]* - A list of entity associations for which INNER JOIN should be used instead of LEFT JOIN. Use the ``dot`` notation to specify a path to a nested association, e.g., ``user.organization``. Each element in the path must be equal to the name of the existing property of an entity. This option can be used to optimize SQL query that is used to load data if some associations are mandatory and cannot be empty.

backend/api/how-to.rst

@@ -680,6 +680,32 @@ the :ref:`oro:api:dump <oroapidump-command>` command with ``--upsert`` option ca
 
     php bin/console oro:api:dump --upsert
 
+.. _configure-validate-operation:
+
+Configure Validate Operation
+----------------------------
+
+By default, :ref:`the validate operation <web-services-api--validate-operation>` is disabled for API resources.
+
+If the validate operation is disabled for an API resource by default, but you need to enable it, use
+the "enable_validation" configuration option in `Resources/config/oro/api.yml` :
+
+.. code-block:: yaml
+
+    api:
+        entities:
+            Acme\Bundle\DemoBundle\Entity\SomeEntity:
+                enable_validation: true
+
+.. note:: Please be aware that when validation requests are processed, the ``rollback_validated_request`` event is dispatched instead of ``post_flush_data`` and ``post_save_data``. Additionally, make sure that no extra actions, such as data indexing or sending emails, are performed when using validation requests. These extra actions can significantly impact the application's performance. For example, if data is indexed but not stored in the database, or if an email is sent for a record that was not created or updated in the database.
+
+To check which entities support the validate operation, use
+the :ref:`oro:api:dump <oroapidump-command>` command with ``--validate`` option:
+
+.. code-block:: none
+
+    php bin/console oro:api:dump --validate
+
 .. _using-a-non-primary-key-to-identify-an-entity:
 
 Using a Non-Primary Key to Identify an Entity