README.md

# A RESTful web service for Multi-Criteria decision Analysis (MCA)
This code implements the Multi-Criteria decision Analysis (MCA) frmaework drafted in Deliverable 3.7 of the EU's Horizon 2020 project 'RISKGONE'.
The service is implmented in Java, exploiting several dependences managed through Maven. 

## Getting started
The user calls the service passing inputs on the criteria weigths and the scores for each possible option to be assessed. Inputs must be formetted in ```json``` as it follows.

First it is important to provide a unique identifier (```uuid```) for reference (otherwise the system will generate one and provide it in the ouptut).

Second, weights for all criteria (```criteria_weights```) to be considered must be specified in an array. Please note that weights hould sum to 1.

Third, scores in each criteria for each option (```options```) must be added in the final array.

The folowing is an example with 2 criteria and 2 options:
```json
{
    "uuid":"e97117a1-d395-47bd-91cd-70c9c2a49e92",
    "criteria_weights": [
        {
            "criterion":"Criterion 1 (benefit)",
            "weight":0.6
        },
        {
            "criterion":"Criterion 2 (risk)",
            "weight":0.4
        }
    ],
    "options": [
        {
            "label":"Option A",
            "scores": [
                {
                    "criterion":"Criterion 1 (benefit)",
                    "score":50
                },
                {
                    "criterion":"Criterion 2 (risk)",
                    "score":-400
                }
            ]
        },
        {
            "label":"Option B",
            "scores": [
                {
                    "criterion":"Criterion 1 (benefit)",
                    "score":70
                },
                {
                    "criterion":"Criterion 2 (risk)",
                    "score":-500
                }
            ]
        }
    ]
}
```

Results are provided in ```json``` as well and as it follows.

First the unique identifier (```uuid```) of the job is provided.

Second, ranking results are presented in a descending order fo preference in an array (```ranks```). Each entry represent the permutation considered (```sequence```) and its final score (```value```). Permutatins are ordered lists of options in a decreasing order of preference.

For instance, in the example below, the sequence first Option A and then Option B has to be preferred:
```json
{
    "uuid":"e97117a1-d395-47bd-91cd-70c9c2a49e92",
    "ranks":[
        {"sequence":"Option A | Option B","value":0.6},
        {"sequence":"Option B | Option A","value":0.4}
    ]
}
```


## Development support
For local debugging and testing purposes, execute the server by running the main method in the McaApplication class.

Then, make sure that curl is correctly installed and working (e.g., on Windows Power shell run first ```Remove-item alias:curl```).

Finally, after having changed directory or added the path to ```src\test\java\no\nilu\riskgone\mca```, run tests as:
```bash
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET -d "@./test_user_case_1.json" "http://localhost:8080/ranking"
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET -d "@./test_user_case_2.json" "http://localhost:8080/ranking"
```

### Technical reference documentation
For further reference, please consider the following sections:
* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)
* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/2.7.4/maven-plugin/reference/html/)
* [Create an OCI image](https://docs.spring.io/spring-boot/docs/2.7.4/maven-plugin/reference/html/#build-image)
* [Spring Web](https://docs.spring.io/spring-boot/docs/2.7.4/reference/htmlsingle/#web)

### Technical guides
The following guides illustrate how to use some features concretely:
* [Building a RESTful Web Service](https://spring.io/guides/gs/rest-service/)
* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/)
* [Building REST services with Spring](https://spring.io/guides/tutorials/rest/)