docs: #377 update mdbook rest info

rust-code-analysis-book/src/commands/rest.md

@@ -1,40 +1,159 @@
 # Rest API
 
-It is possible to run **rust-code-analysis-cli** as a `HTTP` service using
-`REST API` to share data between client and server.
-We will use the port `9090` to show you the possible ways to
-interact with the server.
+**rust-code-analysis-web** is a web server that allows users to analyze source code through a REST API. This service is useful for anyone looking to perform code analysis over HTTP.
 
-## Server
+The server can be run on any host and port, and supports the following main functionalities:
 
-**rust-code-analysis-cli** can act as a server running on your `localhost`
-at a specific port.
+- Remove Comments from source code.
+- Retrieve Function Spans for given code.
+- Compute Metrics for the provided source code.
 
+
+## Running the Server
+
+To run the server, you can use the following command:
+
+```sh
+rust-code-analysis-web --host 127.0.0.1 --port 9090
 ```
-rust-code-analysis-cli --serve --port 9090
+
+- `--host` specifies the IP address where the server should run (default is 127.0.0.1).
+- `--port` specifies the port to be used (default is 8080).
+- `-j` specifies the number of parallel jobs (optional).
+
+## Endpoints
+
+### 1. Ping the Server
+
+Use this endpoint to check if the server is running.
+
+**Request:**
+
+```http
+GET http://127.0.0.1:8080/ping
 ```
 
-The `--port` option sets the port used by the server. One possible value
-could be `9090`.
+**Response:**
 
-## Ping
+- Status Code: `200 OK`
+- Body:
 
-If you want to ping the server, make a `GET` request at this `URL`:
+```json
+{
+  "message": "pong"
+}
+```
 
+### 2. Remove Comments
+
+This endpoint removes comments from the provided source code.
+
+**Request:**
+
+```http
+POST http://127.0.0.1:8080/comments
 ```
-http://127.0.0.1:9090/ping
+
+**Payload:**
+
+```json
+{
+  "id": "unique-id",
+  "file_name": "filename.ext",
+  "code": "source code with comments"
+}
 ```
 
-## Metrics
+- `id`: A unique identifier for the request.
+- `file_name`: The name of the file being analyzed.
+- `code`: The source code with comments.
 
-To get metrics formatted as a `json` file, make a `POST` request at this `URL`:
+**Response:**
 
+```json
+{
+  "id": "unique-id",
+  "code": "source code without comments"
+}
 ```
-http://127.0.0.1:9090/metrics?file_name={filename}&unit={unit}
+
+### 3. Retrieve Function Spans
+
+This endpoint retrieves the spans of functions in the provided source code.
+
+**Request:**
+
+```http
+POST http://127.0.0.1:8080/functions
 ```
 
-The `filename` parameter represents the path to the source file to be analyzed,
-while `unit` is a boolean value that can assume only `0` or `1`. The latter
-tells **rust-code-analysis-cli** to consider only top-level metrics, while the
-former returns detailed metrics for all classes, functions, nested functions,
-and other sub-spaces.
+**Payload:**
+
+```json
+{
+  "id": "unique-id",
+  "file_name": "filename.ext",
+  "code": "source code with functions"
+}
+```
+
+- `id`: A unique identifier for the request.
+- `file_name`: The name of the file being analyzed.
+- `code`: The source code with functions.
+
+**Response:**
+
+```json
+{
+  "id": "unique-id",
+  "spans": [
+    {
+      "name": "function_name",
+      "start_line": 1,
+      "end_line": 10
+    }
+  ]
+}
+```
+
+### 4. Compute Metrics
+
+This endpoint computes various metrics for the provided source code.
+
+**Request:**
+
+```http
+POST http://127.0.0.1:8080/metrics
+```
+
+**Payload:**
+
+```json
+{
+  "id": "unique-id",
+  "file_name": "filename.ext",
+  "code": "source code for metrics"
+  "unit": false
+}
+```
+
+- `id`: Unique identifier for the request.
+- `file_name`: The filename of the source code file.
+- `code`: The source code to analyze.
+- `unit`: A boolean value. `true` to compute only top-level metrics, `false` for detailed metrics across all units (functions, classes, etc.).
+
+**Response:**
+
+```json
+{
+  "id": "unique-id",
+  "language": "Rust",
+  "spaces": {
+    "metrics": {
+      "cyclomatic_complexity": 5,
+      "lines_of_code": 100,
+      "function_count": 10
+    }
+  }
+}
+```