OpenSlides/docs/interfaces/action-service.txt
2021-02-26 15:04:24 +01:00

81 lines
2.8 KiB
Plaintext

// Actions Service Interface
/**
* Executes multiple actions in the context of the user given by the user_id.
* There are two modes of execution:
* atomic=true (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.
* => The whole request is handled atomically.
* atomic=false:
* 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 )[]
}
/**
* If action_data_error_index is given, the error can be directly associated with the
* respective action data. If not, the error is of general fashion and/or not directly
* associated with a single action data.
*
* Note: ActionError can only be used if atomic=false.
*/
interface ActionError {
success: false;
message: string;
action_data_error_index?: number;
}
/**
* JSON resonse with a status code of !=200. If a specific action raised the error,
* use the action_error_index and action_data_error_index to indicate the errored
* action and data, respectively. If there were general errors, both indices must be
* omitted or null.
*
* If the atomic flag was false 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_data_error_index?: number;
}