Enhance the action interface

docs/interfaces/actions-service.txt

@@ -1,25 +1,59 @@
 # Actions Service Interface
 
+/**
+ * JSON resonse with a status code of !=200:
+ * {
+ *     success: false;
+ *     message: string;
+ * }
+ *
+ */
 Exception ActionException(message: string);
 
-
 /**
  * Executes multiple actions in the context of the user given by the user_id.
- * All actions are processed independently.
+ * All actions are depdend: If one fails, nothing is written to the DataStore.
+ * It can be seen as one transaction.
  *
- * TODO: Maybe we do not want to run them independently.
+ * For each action an ActionResult is returned. If an action has an error,
+ * ActionError is used in combination wuth error_index to indicate, which action
+ * resulted in an error.
  *
+ * For general, non specific action-related, errors an ActionException is used.
  *
  * @throws ActionException
  */
-handle_request (payload: Action[], user_id: Id): ActionResult[]
+handle_request (payload: Action[], user_id: Id): ActionsResult | ActionError
 
 interface Action {
     action: string;
-    data: object[];  # An array of action specific data. See JSON schema defintions.
+    data: object[];  # An array of action specific data.
 }
 
-interface ActionResult {
-    success: boolean;
+interace ActionsResult {
+    success: true;
     message: string;
+
+    /**
+     * this is a potentially double-array with entries for each action
+     * and, if not null, an array for each data provided for each action.
+     *
+     *
+     * If an action does not producy a result, the inner array can be omitted and
+     * null can be used. If the inner array is given, each entry must be an object
+     * with the result (e.g. for a create action `{id: <the id>}`) or null.
+
+     * E.g. for valid arrays (two actions with two data entries each):
+     * - [null, null]
+     * - [null, [null, null]]
+     * - [null, [{id: 2}, null]]
+     * - [[{id: 2}, {id: 3}], [{id: 5}, {id: 8}]]
+     **/
+    results: ((object | null)[] | null )[]
+}
+
+interface ActionError {
+    success: false;
+    message: string;
+    error_index: number;
 }