diff --git a/docs/interfaces/presenter-service.txt b/docs/interfaces/presenter-service.txt index 4c27dfa5a..8d09572d0 100644 --- a/docs/interfaces/presenter-service.txt +++ b/docs/interfaces/presenter-service.txt @@ -2,18 +2,50 @@ Exception PresenterException(message: string); +/** + * Executes some presenting function on the server. The term "presenting" means + * a non writing (or modifying) idempotent request. There may be some + * side-effect allowed (like tracking calls to one presenter), but the main + * purpose is to get data of the server, which is not autoupdate-, projector-, or + * icc-data. + * + * Some purposes may be: + * - aggregating of login data + * - managing of whoami, if additional data is needed, that the auth service + * doesn't provide + * - To get history points + * - To get history data + * - To get the installed version + * - To query statistics + * - To calculate recursive trees (e.g. origins of motions; not possible with + * the autoupdate service) + * - to synchronize the servertime for countdowns + * + * @throws PresenterException This exception might be thrown, if there was an + * server error (Http-500-equivalent). For user error (e.g. wrong data) use the + * PresenterError interface + */ +handle_request(user_id: Id, payload: Presenter[]): PresenterResult[] /** - * Presents some (restricted) data without autoupdate. - * - * @throws PresenterException + * This interface specifies what presenter is used with the payload for the call */ -handle_request (payload: Presenter[]): PresenterResult[] - -interface Presenter { - user_id: number; - presentation: TODO; +Interface Presenter { + presenter: string; + data: any; +} + +/** + * A presenter may return anything. This is presenter-specific. But if there was + * an error (user error, not a PresenterException), the response for this + * presenter should follow `PresenterError`. + */ +type PresenterResult = any | PresenterError; + +/** + * A common format for errors. + */ +Interface PresenterError { + error: object; } -/* TODO */ -interface PresenterResult {}