Merge pull request #47 from laboro/ticket/BAP-9949

BAP-9949: Update documentation

src/Oro/Bundle/ApiBundle/Resources/doc/actions.md

@@ -9,6 +9,7 @@ Table of Contents
     - [**get** Action](#get-action)
     - [**get_list** Action](#get_list-action)
     - [**delete** Action](#delete-action)
+    - [**delete_list** Action](#delete_list-action)
     - [**customize_loaded_data** Action](#customize_loaded_data-action)
     - [**get_config** Action](#get_config-action)
     - [**get_relation_config** Action](#get_relation_config-action)
@@ -37,6 +38,7 @@ The following table shows all actions provided out of the box:
 | [get](#get-action) | Returns an entity by its identifier |
 | [get_list](#get_list-action) | Returns a list of entities |
 | [delete](#delete-action) | Deletes an entity by its identifier |
+| [delete_list](#delete_list-action) | Deletes a list of entities |
 | [customize_loaded_data](#customize_loaded_data-action) | Makes modifications of data loaded by [get](#get-action) or [get_list](#get_list-action) actions |
 | [get_config](#get_config-action) | Returns a configuration of an entity |
 | [get_relation_config](#get_relation_config-action) | Returns a configuration of an entity if it is used in a relationship |
@@ -145,6 +147,37 @@ This action has the following processor groups:
 
 Example of usage you can find in the `deleteAction` method of [RestApiController](../../Controller/RestApiController.php).
 
+delete_list Action
+----------
+
+This action is intended to delete a list of entities.
+
+The entities list is builded based on input filters. Please take into account that at least one filter must be specified, otherwise an error raises.
+
+By default the maximum number of entities that can be deleted by one request is 100. This limit was introduced to minimize impact on the server.
+You can change this limit for an entity in `Resources/config/acl.yml`, but please test your limit carefully because a big limit may make a big impact to the server. 
+An example how to change default limit you can read at [how-to](how_to.md#change-the-maximum-number-of-entities-that-can-be-deleted-by-one-request).
+
+The context class: [DeleteListContext](../../Processor/DeleteList/DeleteListContext.php). Also see [Context class](#context-class) for more details.
+
+The main processor class: [DeleteListProcessor](../../Processor/DeleteListProcessor.php).
+
+Existing worker processors: [processors.delete_list.yml](../../Resources/config/processors.delete_list.yml) or run `php app/console oro:api:debug delete_list`.
+
+This action has the following processor groups:
+
+| Group Name | Responsibility of Processors | Description |
+| --- | --- | --- |
+| initialize | Initializing of the context | Also the processors from this group are executed when Data API documentation is generated. |
+| security_check | Checking whether an access to the requested resource is granted | |
+| normalize_input | Preparing input data to be ready to use by processors from the next groups | |
+| build_query | Building a query that will be used to load an entities list to be deleted | |
+| load_data | Loading an entities list that should be deleted and save it in the `result` property of the context | |
+| delete_data | Deleting the entities list stored in the `result` property of the context | |
+| normalize_result | Building the action result | The processors from this group are executed even if a processor from previous groups throws an exception. Details how it is implemented you can find in [RequestActionProcessor](../../Processor/RequestActionProcessor.php). |
+
+Example of usage you can find in the `deleteListAction` method of [RestApiController](../../Controller/RestApiController.php).
+
 customize_loaded_data Action
 ----------------------------
 

src/Oro/Bundle/ApiBundle/Resources/doc/configuration.md

@@ -165,7 +165,7 @@ Each entity can have next properties:
 * **order_by** *array* The property can be used to configure default ordering. The item key is the name of a field. The value can be `ASC` or `DESC`.
 * **hints** *array* Sets [Doctrine query hints](http://doctrine-orm.readthedocs.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#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]`.
 * **post_serialize** *callable* A handler to be used to modify serialized data.
-* **delete_handler** *string* The id of a service that should be used to delete entity by the [delete](./actions.md#delete-action) action. By default the [oro_soap.handler.delete](../../../SoapBundle/Handler/DeleteHandler.php) service is used.
+* **delete_handler** *string* The id of a service that should be used to delete entity by the [delete](./actions.md#delete-action) and [delete_list](./actions.md#delete_list-action) actions. By default the [oro_soap.handler.delete](../../../SoapBundle/Handler/DeleteHandler.php) service is used.
 
 Example:
 
@@ -349,6 +349,7 @@ By default, the following permissions are used to restrict access to an entity i
 | get | VIEW |
 | get_list | VIEW |
 | delete | DELETE |
+| delete_list | DELETE |
 
 
 Examples of `actions` section configuration:

src/Oro/Bundle/ApiBundle/Resources/doc/how_to.md

@@ -34,6 +34,7 @@ By default, the following permissions are used to restrict access to an entity i
 | get | VIEW |
 | get_list | VIEW |
 | delete | DELETE |
+| delete_list | DELETE |
 
 In case if you want to change permission or disable access checks for some action, you can use the `acl_resource` option of `actions` configuration section.