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 service is reachable from a web server under the ```/ranking``` directory. For instance, if the web server is running on the localhost and listening on the standard http port, the service is reachable at http://localhost:8080/ranking.

Once running APIs are available as JSON objects (http://localhost:8080/docs/api) or as a Swagger User Interface (http://localhost:8080/docs/swagger-ui.html).

### Calling the service
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
                }
            ]
        }
    ]
}
```

### DISCLAIMER: input errors
Please note that this software, as any other, has some boundaries of validity and in being able to manage messy or faulty inputs.

First, the JSON provided to the service must be correctly formatted, otherwise the service won't be able to parse it and will results a JSON message containing ```"status":500,"error":"Internal Server Error"```.

Second, except for the optional UUID field, all others must be fully reported in the JSON input. Thus, for instance and referring to the example above, an option with only one criterion would generate another internal error.

Third, the scores reported in the JSON file must be 'complete'. This means that users must assign a score to each criterion in each option. If scores are missing, users should take a conservative approach such as assigning the lowest score observed or observable for that criterion. Please note that JSON ```null``` values, though formatted correctly, will be translated to 0 and thus may generate undersired outcomes.

However, the service is capable of dealing with two types of errors. First, the service will rescale weights if the ones provided do not sum up to 1. Second, as long as all scores are reported, it is irrelevant their ordering within each option. These features can be tested by running the file ```test_user_case_3.json``` in the test directory.

### Results
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 of 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"
```
To make the jar file and be sure it will work, run a clean Maven install from the ```web_service``` directory. For instance on Windows systems the command would be:
```bash
& ".\mvnw.cmd" clean install -U
```
***
## References
### Technical documentation
For further reference on using Spring Boot in Java and Maven, 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)

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/)