Refine presenter service

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 {}