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. It provides several endpoints to extract information such as removing comments, retrieving function spans, and computing various metrics. 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
+    }
+  }
+}
+```