# **Flame CLMC Service Documentation**

#### **Authors**

|Authors|Organisation|
|---|---|
|[Nikolay Stanchev](mailto:ns17@it-innovation.soton.ac.uk)|[University of Southampton, IT Innovation Centre](http://www.it-innovation.soton.ac.uk)|

#### 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, 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 Body 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 Body 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 Body 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 in a malformed state.

* Response Body 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* field. If the aggregator
is running in a malformed state, the response will also indicate this with two additional fields - *malformed* and *comment*.

* Response Body Example:

```json
{
"aggregator_running": true
}
```

* Response Body 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 Body 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 Body 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.

#### Installing and running the CLMC service (development mode)

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.

```
pip install virtualenvwrapper
```

To create a virtual environment use the **mkvirtualenv** command:

```
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:

```
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-webservice folder:
```
cd src/clmc-webservice
```

Test the CLMC service using **tox** along with the ***tox.ini*** configuration file. If tox is not installed run:

```
pip install tox
```

After it is installed, simply use the **tox** command:

```
tox
```

Then install the service in development mode.

```
pip install -e .
```

Finally, start the service on localhost by using pyramid's **pserve**:

```
pserve development.ini --reload
```

You should now be able to make requests to the CLMC service on http://localhost:9080/aggregator/config and http://localhost:9080/aggregator/control.