First documentation of the API for the CLMC service

docs/clmc-service.md

@@ -33,3 +33,148 @@
 
 This document describes the CLMC service and its API endpoints. The CLMC service is implemented in the *Python* framework called **Pyramid**.
 It offers different API endpoints to configure and control the aggregator, which is an essential part in the process of measuring the end-to-end performance.
+All source code, tests and configuration files of the service can be found in the **src/clmc-webservice** folder.
+
+#### API Endpoints
+
+* **GET** ***/aggregator/config***
+
+    This API method retrieves information about the configuration of the aggregator.
+    
+    * Response:
+        
+        Returns a JSON-formatted response with the configuration data of the aggregator - *aggregator_report_period*, *aggregator_database_name*,
+        *aggregator_database_url*.
+        
+    * Response Example:
+        
+        ```json
+        {
+          "aggregator_report_period": 5,
+          "aggregator_database_name": "E2EMetrics",
+          "aggregator_database_url": "http://172.40.231.51:8086"
+        }
+        ```
+
+* **PUT** ***/aggregator/config***
+
+    This API method updates the configuration of the aggregator.
+    
+    * Request:
+        
+        Expects a JSON-formatted request body with the new configuration of the aggregator. The body should contain only
+        three key fields - *aggregator_report_period* (positive integer, seconds), *aggregator_database_name* and *aggregator_database_url* (a valid URL).
+        
+    * Request Example: 
+    
+        ```json
+        {
+          "aggregator_report_period": 25,
+          "aggregator_database_name": "E2EMetrics",
+          "aggregator_database_url": "http://172.50.231.61:8086"
+        }
+        ```
+    
+    * Response:
+        
+        The body of the request is first validated before updating the configuration. If validation is successful, returns 
+        a JSON-formatted response with the new configuration data. Otherwise, an **HTTP Bad Request** response is returned.
+        
+    * Response Example:
+    
+        ```json
+        {
+          "aggregator_report_period": 25,
+          "aggregator_database_name": "E2EMetrics",
+          "aggregator_database_url": "http://172.50.231.61:8086"
+        }
+        ```
+    
+    * Notes:
+    
+        If the configuration is updated, while the aggregator is running, it is not automatically restarted. An explicit API call
+        must be made with a *restart* request to apply the updated configuration. In the case of such PUT request as the one described
+        above, the response will contain more information indicating that the configuration of the aggregator is malformed
+        
+        * Response Example:
+        
+            ```json
+            {
+              "aggregator_report_period": 125,
+              "aggregator_database_name": "E2EMetrics",
+              "aggregator_database_url": "http://172.50.231.61:8086/",
+              "malformed": true,
+              "comment": "Aggregator is running in a malformed state - it uses an old version of the configuration. Please, restart it so that the updated configuration is used."
+            }
+            ```
+
+* **GET** ***/aggregator/control***
+
+    This API method retrieves information about the status of the aggregator - whether it is running or not.
+    
+    * Response:
+        
+        Returns a JSON-formatted response with the status data of the aggregator - *aggregator_running*. If the aggregator
+        is running in a malformed state, the response will also indicate this with two additional fields - *malformed* and *comment*
+        
+    * Response Example:
+        
+        ```json
+        {
+          "aggregator_running": false
+        }
+        ```
+        
+    * Response Example - for malformed configuration:
+    
+        ```json
+        {
+          "aggregator_running": true,
+          "malformed": true,
+          "comment": "Aggregator is running in a malformed state - it uses an old version of the configuration. Please, restart it so that the updated configuration is used."
+        }
+        ```
+
+* **PUT** ***/aggregator/control***
+
+    This API method updates the status of the aggregator - a user can start, stop or restart it.
+    
+    * Request:
+        
+        Expects a JSON-formatted request body with the new status of the aggregator. The body should contain only one key
+        field - *action* (the action to undertake, which can be **start**, **restart** or **stop**)
+        
+    * Request Example: 
+    
+        ```json
+        {
+          "action": "start"
+        }
+        ```
+    
+    * Response:
+        
+        The body of the request is first validated before taking any actions. If the action is not one of the listed above,
+        then the validation will fail. If validation is successful, returns a JSON-formatted response with the new status of
+        the aggregator. Otherwise, an **HTTP Bad Request** response is returned.
+        
+    * Response Example:
+    
+        ```json
+        {
+          "aggregator_running": true
+        }
+        ```
+        
+    * Notes:
+    
+        * If a **start** action is requested, while the aggregator is running, then the request will be ignored. To restart the
+        aggregator, a user should use a **restart** action.
+        
+        * If a **stop** action is requested, while the aggregator is not running, then the request will be ignored.
+        
+        * A request with a **restart** action, while the aggregator is not running, has the same functionality as a request
+        with a **start** action.
+        
+        * The functionality of a request with a **restart** action is the same as the functionlity of a **stop** action
+        followed by a **start** action.
\ No newline at end of file