Updates CLMC service documentation

docs/clmc-service.md

@@ -32,9 +32,80 @@
 #### Description
 
 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 as well as a CRUD API for service function endpoints configuration data and Graph API for calculating round trip time. All source code, tests and configuration files of the service can be found in the **src/service** folder.
+It offers different API endpoints such as GraphAPI for calculating round trip time, CRUD API for service function endpoints 
+configuration data and Alerts API for creating and subscribing to alerts in Kapacitor. All source code, tests and 
+configuration files of the service can be found in the **src/service** folder.
 
 
+## Alerts API Endpoints
+
+* **POST** ***/alerts***
+
+    This API method can be used to send an alert specification document, which is then used by the CLMC service to create
+    alert tasks and subscribe alert handlers to those tasks in Kapacitor. For further information on the alert specification
+    document, please check the [CLMC Alert Specification Documentation](AlertsSpecification.md).
+
+    * Request:
+        
+        Expects a YAML-formatted file in the request body referenced with ID *alert-spec* representing the alert specification 
+        document. This document is then parsed with the openstack TOSCA parser (https://github.com/openstack/tosca-parser/tree/master/toscaparser)
+        and validated against the CLMC alerts specification schema. 
+        
+    * Request example for sending such request with curl:
+    
+        `curl -F "alert-spec=@alert-specification.yaml" http://loclahost:9080/alerts`
+        
+        where **alert-specification.yaml** is the path to the specification file.
+    
+    * Response:
+        
+        The response of this request is a JSON-formatted content, which contains the SFC and SFC instance identifiers
+        from the alert specification along with errors encountered when interacting with Kapacitor.
+        
+        Returns a 400 Bad Request if the request does not contain a yaml file referenced with ID **alert-spec**.
+        
+        Returns a 400 Bad Request if the alert specification file is not a valid YAML file.
+        
+        Returns a 400 Bad Request if the alert specification file cannot be parsed with the TOSCA parser.
+        
+        Returns a 400 Bad Request if the alert specification file fails validation against the CLMC alerts specification schema.
+        
+    * Response Body Example:
+    
+        ```json
+        {
+          "msg": "Alerts specification has been successfully validated and forwarded to Kapacitor", 
+          "service_function_chain_id": "<sfc_id>",
+          "service_function_chain_instance_id": "<sfc_instance_id>"
+        }
+        ```
+        
+        If the CLMC service encounters any errors when creating alerts and handlers in Kapacior, they will
+        be reported in the response as two lists of error objects (one for alert tasks and one for alert handlers):
+     
+        ```json
+        {
+          "msg": "Alerts specification has been successfully validated and forwarded to Kapacitor", 
+          "service_function_chain_id": "<sfc_id>",
+          "service_function_chain_instance_id": "<sfc_instance_id>",
+          "triggers_action_errors": [
+                  {
+                      "trigger": "<trigger ID the error is related to>",
+                      "handler": "<handler URL the error is related to>",
+                      "policy": "<policy ID the error is related to>",
+                      "error": "<error message returned from Kapacitor>"
+                  }
+          ],
+          "triggers_specification_errors": [
+                {
+                      "trigger": "<trigger ID the error is related to>",
+                      "policy": "<policy ID the error is related to>",
+                      "error": "<error message returned from Kapacitor>"
+                }
+          ]
+        }
+        ```
+
 ## Graph API Endpoints
 
 * **Assumptions**
@@ -565,58 +636,3 @@ It offers different API endpoints to configure and control the aggregator as wel
           "sr": "sr_1"
            }
         ```
-
-## Installing and running the CLMC service
-
-Before installing the CLMC service and its dependencies, it is recommended to use a python virtual environment. To easily
-manage virtual environments, **virtualenvwrapper** can be used.
-
-```shell
-pip3 install virtualenvwrapper
-```
-
-To create a virtual environment use the **mkvirtualenv** command:
-
-```shell
-mkvirtualenv CLMC
-```
-
-When created, you should already be set to use the new virtual environment, but to make sure of this use the **workon** command:
-
-```shell
-workon CLMC
-```
-
-Now, any installed libraries will be installed relative to this environment only.
-
-The easiest way to install and use the CLMC service locally is to use **pip**. Navigate to the clmc-service folder:
-
-```shell
-cd src/service
-```
-
-Test the CLMC service using **tox** along with the ***tox.ini*** configuration file. If tox is not installed run:
-
-```shell
-pip3 install tox
-```
-
-After it is installed, simply use the **tox** command:
-
-```shell
-tox
-```
-
-Then install the service.
-
-```shell
-pip3 install .
-```
-
-Finally, start the service on localhost by using pyramid's **pserve** command line utility:
-
-```shell
-pserve production.ini
-```
-
-You should now be able to make requests to the CLMC service on the various API endpoints.