Merge pull request #5696 from FinnStutzenstein/actionServiceInterface

Enhance the action interface

docs/interfaces/action-service.txt

@@ -0,0 +1,70 @@
+// Actions Service Interface
+
+/**
+ * Executes multiple actions in the context of the user given by the user_id.
+ * There are two modes of execution:
+ * atomic=false (default):
+ *   All actions are validated in common, so if one action or one payload of
+ *   one action fails, the request is aborted with an ActionException indicating
+ *   the problematic action with both indices.
+ * atomic=true:
+ *   Each action is validated by it's own. If there is an error, the error must
+ *   be reported via an ActionError in the ActionsResponse. The actions result
+ *   is not written into the Datastore. It might raise an ActionException if the
+ *   single write request to the Datastore fails (e.g. because of locking there)
+ *
+ * For general, non specific action-related, errors an ActionException is used.
+ *
+ * @throws ActionException
+ */
+handle_request(payload: Action[], user_id: Id, atomic?: boolean): ActionsResponse
+
+interface Action {
+    action: string;
+    data: object[];
+}
+
+interace ActionsResponse {
+    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 produce 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}]]
+     *
+     *
+     * To report errors, use the ActionError format!
+     **/
+    results: ((object | ActionError | null)[] | null )[]
+}
+
+interface ActionError {
+    success: false;
+    message: string;
+}
+
+/**
+ * JSON resonse with a status code of !=200. If a specific action raised the error,
+ * use the action_error_index and action_payload_error_index to indicate the errored
+ * action and payload. If there were general errors, both indices must be omitted or null.
+ *
+ * If the atomic flag was true in the request, it is not allowed to send
+ * action-specific errors with this exception. It must be responded with an
+ * ActionError through ActionsResponse (resulting in a status code of 200).
+ */
+Exception ActionException {
+    success: false;
+    message: string;
+    action_error_index?: number;
+    action_payload_error_index?: number;
+}

docs/interfaces/actions-service.txt

@@ -1,25 +0,0 @@
-# Actions Service Interface
-
-Exception ActionException(message: string);
-
-
-/**
- * Executes multiple actions in the context of the user given by the user_id.
- * All actions are processed independently.
- *
- * TODO: Maybe we do not want to run them independently.
- *
- *
- * @throws ActionException
- */
-handle_request (payload: Action[], user_id: Id): ActionResult[]
-
-interface Action {
-    action: string;
-    data: object[];  # An array of action specific data. See JSON schema defintions.
-}
-
-interface ActionResult {
-    success: boolean;
-    message: string;
-}