Merge pull request #5696 from FinnStutzenstein/actionServiceInterface
Enhance the action interface
This commit is contained in:
commit
315bd7cdf3
70
docs/interfaces/action-service.txt
Normal file
70
docs/interfaces/action-service.txt
Normal file
@ -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;
|
||||
}
|
@ -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;
|
||||
}
|
Loading…
Reference in New Issue
Block a user