Decision-Support-Toolbox-Usage.md

@@ -139,6 +139,134 @@ Below the user may find an example of the response payload to be retrieved upon
 }
 ```
 
+## MCDM
+As mentioned in the description, the only non-LUT related API is the one implementing the Multi-Criteria Decision Making FBWM algorithm. The same endpoint as the one for the LUT is used. The FBWM path is ```/decide```.
+
+```/decide``` receives POST requests on its path. For a valid response, the following assumptions must hold:
+    - the refactorings listed in the request body are aligned with the LUT content 
+    - the body of the request follows the below format:
+
+```
+{
+  "prefs": {
+    "best": {
+      "energy": false,
+      "td": false,
+      "sec": true
+    },
+    "worst": {
+      "energy": false,
+      "td": true,
+      "sec": false
+    },
+    "bw": 1,
+    "bj": 2,
+    "jw": 3,
+    "sc": true
+  },
+  "refs": [
+    {
+      "name": "Dead_Code",
+      "impacts": {
+        "Energy": "No impact",
+        "Technical Debt": "Slightly Worsen",
+        "Security": "Improve"
+      },
+      "vectors": {
+        "1v2": {
+          "x": 0,
+          "y": 0,
+          "len": 1,
+          "ang": 180
+        },
+        "2v3": {
+          "x": 0,
+          "y": 0,
+          "len": 2.23606797749979,
+          "ang": 334
+        },
+        "1v3": {
+          "x": 0,
+          "y": 0,
+          "len": 2,
+          "ang": 0
+        }
+      },
+      "count": 10
+    }
+  ]
+}
+```
+
+The table below summarizes the meaning (if relevant) of each field.
+
+|Field|Meaning|
+|-----|-------|
+|```refs```|The set of user preferences, as described in the [FBWM paper][fb].|
+|```sc```|A user flag suggesting whether FBWM should ignore each option's count or not.|
+|```refs```|The set of available decisions/refactorings. If one ignored the count field, the rest of ```refs``` equals to an array of LUT responses to refactoring-specific queries.|
+|```count```|The number of times each option was proposed by the analysis tools.|
+
+> **CAUTION:** ```/decide``` has been tested only through the Decision Support - TradeOff Manager front-end. More precisely, the code of the API and the checks performed are structured based on the data interface defined in the mentioned frontend code. Thus, interaction with the FBWM component through third-party requests is not advised.
+
+If all goes well, FBWM will respond with something like the following:
+
+```
+{
+  "xi": [
+    1.1935062201239977,
+    0.34461459948898315,
+    0.34461459948896517,
+    0.34461459948897527,
+    0.42729976112471235,
+    0.4272997611247274,
+    0.6842569181589543,
+    0.18525944654728993,
+    0.18525944654725612,
+    0.18525944654729093
+  ],
+  "iterations": 5,
+  "prop": {
+    "name": "Dead_Code",
+    "val": 0.17
+  },
+  "cats": [
+    "Dead_Code"
+  ],
+  "series": [
+    {
+      "name": "Energy",
+      "data": [
+        0.01
+      ]
+    },
+    {
+      "name": "Technical Debt",
+      "data": [
+        -0.02
+      ]
+    },
+    {
+      "name": "Security",
+      "data": [
+        0.18
+      ]
+    }
+  ],
+  "seriesTotal": [
+    {
+      "name": "Total Calculated Value",
+      "data": [
+        0.17
+      ]
+    }
+  ]
+}
+```
+
+Again, the response is structured so as to complement the tool's frontend code.
+
 [EP]: <http://147.102.37.20:8062/>
 [HBA]: <https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication>
 [sdk]: <http://160.40.52.130:3000/>
+[fb]: <https://www.sciencedirect.com/science/article/pii/S0950705117300114?casa_token=aBGN55zUcz4AAAAA:BqvXuAOzU8utEQINJ4OXFgLsW4NUBAIxdxnWu9dnH90rBkorbYeIPGPKx0Epy1oeljaiSeLr>
\ No newline at end of file