Skip to content

Commit 87a0c40

Browse files
MirkoZETAMirkoZETA
committed
Enhance documentation and code readability:
 - Improved README with clearer formatting and structure - Enhanced API documentation in backend.py - Updated development guide with clearer instructions - Fixed syntax error in test_main.cpp - Added test coverage files to .gitignore - Improved code comments and function documentation
1 parent 2c10471 commit 87a0c40

6 files changed

Lines changed: 668 additions & 362 deletions

File tree

‎.github/workflows/README_DEV.md‎

Lines changed: 71 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,93 @@
1-
# Flex Net Sim Backend API - Development and Deployment Instructions
1+
# Flex Net Sim API - Development Guide
22

3-
This document is for developers who want to set up, develop, and deploy the Flex Net Sim Backend API.
3+
This guide helps developers set up, test, and deploy the Flex Net Sim Backend API.
44

55
## Prerequisites
66

7-
* Python 3.9 or higher
8-
* g++ (GNU C++ Compiler)
9-
* Docker (for containerization)
10-
* Google Cloud SDK (for deployment to Google Cloud Run)
11-
* A Google Cloud Project with Cloud Run API enabled.
7+
* Python 3.9+
8+
* g++ (GNU C++ Compiler)
9+
* Docker (for containerization)
10+
* A Google Cloud Project with Cloud Run API enabled
11+
12+
## Local Development Setup
13+
14+
1. **Clone the repository:**
15+
```bash
16+
git clone https://github.com/MirkoZETA/FlexNetSim-API.git
17+
cd FlexNetSim-API
18+
```
19+
20+
2. **Set up Python environment:**
21+
```bash
22+
# Create virtual environment
23+
python3 -m venv .venv
24+
25+
# Activate (Linux/macOS)
26+
source .venv/bin/activate
27+
28+
# Activate (Windows)
29+
.venv\Scripts\activate
30+
31+
# Install dependencies
32+
pip install -r requirements.txt
33+
```
34+
35+
3. **Run the application:**
36+
```bash
37+
flask --app backend run
38+
```
39+
The API will be available at `http://127.0.0.1:5000`.
40+
41+
4. **Test the API:**
42+
```bash
43+
# Test help endpoint
44+
curl http://127.0.0.1:5000/help
45+
46+
# Test simulation endpoint
47+
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
48+
```
49+
50+
## Testing
51+
52+
Run the test suite to ensure code quality:
1253

13-
## Getting Started (Local Development)
14-
15-
1. **Clone the repository:**
16-
```bash
17-
git clone [https://github.com/MirkoZETA/FlexNetSim-API.git](https://github.com/MirkoZETA/FlexNetSim-API.git)
18-
cd flask-simulation-backend
19-
```
20-
21-
2. **Create a Python virtual environment (recommended):**
22-
```bash
23-
python3 -m venv .venv
24-
```
25-
26-
On Linux/macOS:
27-
```bash
28-
source .venv/bin/activate
29-
```
30-
31-
On Windows
32-
```bash
33-
.venv\Scripts\activate
34-
```
35-
3. **Install Python dependencies:**
36-
```bash
37-
pip install -r requirements.txt
38-
```
39-
40-
4. **Run the Flask backend:**
41-
```bash
42-
flask --app backend run
43-
```
44-
The backend will be accessible at `http://127.0.0.1:5000`.
45-
46-
5. **Test**:
47-
```bash
48-
curl http://127.0.0.1:5000/help
49-
```
50-
or
51-
```bash
52-
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
53-
```
54+
```bash
55+
pytest tests/
56+
```
5457

55-
### Dockerization
58+
## Docker Deployment
5659

57-
To build the Docker image:
60+
Build and run the Docker container locally:
5861

5962
```bash
63+
# Build image
6064
docker build -t fns-api .
65+
66+
# Run container
67+
docker run -p 5000:5000 fns-api
6168
```
6269

63-
## GCloud Deployment Configuration
70+
## Google Cloud Deployment Configuration
6471

65-
As a prerequisite is mandatory to apply the following steps to the GCloud project for the docker image build and upload to artifacts, and also service account creation and IAM policy binding:
72+
The following steps are required to configure your Google Cloud project for deployment. These steps focus solely on the Google Cloud setup, not the GitHub Actions workflow configuration.
6673

6774
[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)
6875

69-
This video will guide you through the necessary configurations in the Google Cloud Console to prepare your project for Cloud Run deployments using GitHub Actions.
76+
**Note: This video demonstrates only the Google Cloud Console configurations.** The YAML workflow files shown in the video may be outdated and are not necessary for current deployments.
77+
78+
Follow the Google Cloud setup steps from the video, focusing on:
79+
80+
* Creating a project
81+
* Setting up Docker repositories
82+
* Creating service accounts
83+
* Configuring permissions
7084

71-
**Key Reminders from the Video & for Successful Deployment:**
85+
**Key Information to Record During Setup:**
7286

73-
* **Keep Track of Docker Image Name, Project ID:** Note these down during the video configuration, as you will need them in subsequent steps and for your GitHub Actions workflow.
74-
* **Service Account Email:** Ensure you create a Service Account as shown in the video and securely download and store the JSON key file. You'll also need to note the Service Account's email address.
87+
* **Docker Image Name and Project ID:** Note these for your deployment process
88+
* **Service Account Email:** Create a Service Account, download its JSON key file, and record the email address
7589

76-
**Post-Configuration Steps (using `gcloud` and `cloud-run`):**
90+
**Post-Configuration Steps (using `gcloud` CLI):**
7791

7892
1. Activate necessary apis:
7993

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,8 @@ simulation.out
55
.vscode/
66

77
# macOS
8-
**/.DS_Store
8+
**/.DS_Store
9+
10+
# Test files
11+
.coverage
12+
htmlcov

‎README.md‎

Lines changed: 52 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,83 @@
11
# Flex Net Sim Backend API
22

3-
Welcome to the Flex Net Sim Backend API repository.
3+
A lightweight API for running optical network simulations with [Flex Net Sim C++](https://gitlab.com/DaniloBorquez/flex-net-sim).
44

5-
This is the **publicly accessible backend API** for the [Flex Net Sim](https://gitlab.com/DaniloBorquez/flex-net-sim) project.
5+
## Overview
66

7-
This API provides a **hands-on demonstration**, enabling users to quickly execute pre-configured network simulations and gain an initial understanding of Flex Net Sim's capabilities.
7+
The FlexNetSim Backend API provides:
88

9-
Through simple POST requests, initiated via command-line tools or the [playground page](www.in-progress.com), users can experiment with a defined set of parameters and algorithms. This allows for exploration of fundamental network simulation concepts using Flex Net Sim.
9+
- **Hands-on demonstration** of optical network simulation capabilities
10+
- **Simplified access** to core Flex Net Sim features
11+
- **Quick experimentation** with pre-configured network topologies and parameters
1012

11-
It is important to note that **this API is intentionally designed as a limited demonstration platform**. It serves as a **simplified method of accessing** and showcasing the **basic functionalities** of Flex Net Sim. **It is not intended for complex simulations or for algorithm customization.** Algorithm customization is a core strength of Flex Net Sim, and this advanced capability is exclusively unlocked when working directly with **the library**.
13+
This API serves as an introduction to the full Flex Net Sim library, allowing users to explore basic network simulation concepts through simple HTTP requests.
1214

13-
The purpose of this API is to introduce users to Flex Net Sim and encourage exploration of **the full library** for advanced simulation tasks. **The full library** offers significantly greater power, flexibility, and customization potential.
15+
## Important Limitations
1416

15-
For users interested in progressing beyond this introductory API, comprehensive resources and documentation are available at the official [Flex Net Sim documentation](https://flex-net-sim-fork.readthedocs.io/stable/).
17+
This API is intentionally designed as a limited demonstration platform:
1618

17-
For **Development and Deployment Instructions** of this API (the playground itself), please refer to [README_DEV.md](README_DEV.md).
19+
- **Not intended** for complex simulations or algorithm customization
20+
- Provides access to **basic functionalities** only
21+
- For advanced simulation tasks, users should explore **the full library**
22+
23+
For comprehensive resources, see the [Flex Net Sim documentation](https://flex-net-sim-fork.readthedocs.io/stable/).
24+
25+
For development and deployment instructions for this API, refer to [README_DEV.md](.github/workflows/README_DEV.md).
1826

1927
## API Endpoints
2028

2129
### `/run_simulation` (POST)
2230

23-
This endpoint runs a Flex Net Sim simulation based on the parameters provided in the JSON request body.
31+
Runs a network simulation with the provided parameters.
2432

25-
**Request Body Parameters:**
33+
#### Request Parameters
2634

27-
| Parameter | Type | Description | Allowed Values | Default Value | Constraints |
28-
| :---------------- | :-------------- | :----------------------------------------------------- | :---------------------------- | :------------ | :-------------------- |
29-
| `algorithm` | `string` | Routing and spectrum assignment algorithm to use. | `FirstFit`, `ExactFit` | `FirstFit` | |
30-
| `networkType` | `integer` | Type of optical network. | `1` | `1` | Only `1` (EON) available |
31-
| `goalConnections`| `integer` | Target number of connection requests for the simulation.| | `100000` | Must be integer > 0 |
32-
| `confidence` | `number (float)`| Confidence level for the simulation results. | | `0.05` | Must be > 0 |
33-
| `lambdaParam` | `number (float)` | Arrival rate (lambda) of connection requests. | | `1.0` | Must be > 0 |
34-
| `mu` | `number (float)`| Service rate (mu) of connection requests. | | `10.0` | Must be > 0 |
35-
| `network` | `string` | Network topology to simulate. | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` | |
36-
| `bitrate` | `string` | Type of bitrate allocation. | `fixed-rate`, `flex-rate` | `bitrate` | |
37-
| `K` | `integer` | Number of paths to consider. | | `3` | |
35+
| Parameter | Type | Description | Allowed Values & Constraints | Default |
36+
|---------------|---------|----------------------------|-------------------------------------------------|-----------|
37+
| `algorithm` | `string` | RSA algorithm | `FirstFit`, `ExactFit` | `FirstFit` |
38+
| `networkType` | `integer` | Network type | Only `1` (EON) supported | `1` |
39+
| `goalConnections` | `integer` | Target connection requests | Must be > 0 and < 10,000,000 | `100000` |
40+
| `confidence` | `float` | Confidence level | Must be > 0 and < 1.0 | `0.05` |
41+
| `lambdaParam` | `float` | Arrival rate | Must be > 0 | `1.0` |
42+
| `mu` | `float` | Service rate | Must be > 0 | `10.0` |
43+
| `network` | `string` | Network topology | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` |
44+
| `bitrate` | `string` | Bitrate type | `fixed-rate`, `flex-rate` | `fixed-rate` |
45+
| `K` | `integer` | Path count | Must be > 0 and ≤ 6 | `3` |
3846

39-
**Example `curl` request with no parameters (defaults applied):**
47+
#### Example: Default Parameters
4048

4149
```bash
42-
curl -X POST -H "Content-Type: application/json" -d '{}' https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
50+
curl -X POST -H "Content-Type: application/json" -d '{}' \
51+
https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
4352
```
4453

45-
**Example `curl`request with all parameters specified:**
54+
#### Example: Custom Parameters
4655

4756
```bash
4857
curl -X POST -H "Content-Type: application/json" \
49-
-d '{ "algorithm": "FirstFit",
50-
"networkType": 1,
51-
"goalConnections": 1000000,
52-
"confidence": 0.05,
53-
"lambdaParam": 120,
54-
"mu": 1,
55-
"network": "NSFNet",
56-
"bitrate": "fixed-rate"
57-
}' \
58-
https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
59-
```
60-
61-
**Response**:
62-
- `200` OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
63-
```JSON
64-
{
65-
"output": "string",
66-
"error": "string"
67-
}
68-
```
69-
- `400` Bad Request: Indicates an error in the request, such as missing or invalid parameters. The response body will be a JSON object with an `error` field describing the issue.
70-
- `500` Internal Server Error: Indicates a server-side error, either during compilation or simulation execution. The response body will be a JSON object with `error` and "details" fields providing more information about the error.
58+
-d '{
59+
"algorithm": "FirstFit",
60+
"networkType": 1,
61+
"goalConnections": 100000,
62+
"confidence": 0.05,
63+
"lambdaParam": 120,
64+
"mu": 1,
65+
"network": "NSFNet",
66+
"bitrate": "fixed-rate"
67+
}' \
68+
https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
69+
```
70+
71+
#### Response Codes
72+
73+
- `200 OK`: Success. Returns `{"output": "...", "error": ""}`
74+
- `400 Bad Request`: Invalid parameters
75+
- `500 Internal Server Error`: Server-side error
7176

7277
### `/help` (GET)
7378

74-
This endpoint provides detailed information about the `/run_simulation` endpoint, including the expected request structure, parameters, and response formats.
79+
Returns detailed API documentation.
7580

76-
**Request**:
7781
```bash
7882
curl https://fns-api-cloud-run-787143541358.us-central1.run.app/help
7983
```

0 commit comments

Comments
 (0)