ospab.host/ospabhost/backend/API_DOCUMENTATION.md

API Documentation - Server Management

Base URL

http://localhost:5000/api

Authentication

All endpoints require Bearer token authentication via the Authorization header:

Authorization: Bearer <access_token>

---

Server Management Endpoints

1. Get All Servers

GET /server

Returns a list of all servers for the authenticated user.

Response:

[
  {
    "id": 1,
    "userId": 1,
    "tariffId": 2,
    "osId": 1,
    "status": "running",
    "proxmoxId": 100,
    "ipAddress": "10.0.0.5",
    "rootPassword": "encrypted_password",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "os": {
      "id": 1,
      "name": "Ubuntu 22.04",
      "type": "linux"
    },
    "tariff": {
      "id": 2,
      "name": "Базовый",
      "price": 300
    }
  }
]

---

2. Get Server Details

GET /server/:id

Returns detailed information about a specific server.

Parameters:

• id (path) - Server ID

Response:

{
  "id": 1,
  "status": "running",
  "proxmoxId": 100,
  "ipAddress": "10.0.0.5",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "os": { "name": "Ubuntu 22.04", "type": "linux" },
  "tariff": { "name": "Базовый", "price": 300 }
}

---

3. Get Server Status and Statistics

GET /server/:id/status

Returns real-time status and resource usage statistics.

Parameters:

• id (path) - Server ID

Response:

{
  "id": 1,
  "status": "running",
  "stats": {
    "status": "success",
    "data": {
      "vmid": 100,
      "status": "running",
      "uptime": 3600,
      "cpu": 0.15,
      "memory": {
        "used": 536870912,
        "max": 2147483648,
        "usage": 25.0
      },
      "disk": {
        "used": 5368709120,
        "max": 21474836480,
        "usage": 25.0
      },
      "network": {
        "in": 104857600,
        "out": 52428800
      },
      "rrdData": [...]
    }
  }
}

---

4. Create New Server

POST /server/create

Creates a new LXC container.

Request Body:

{
  "osId": 1,
  "tariffId": 2
}

Response:

{
  "id": 1,
  "status": "creating",
  "proxmoxId": 100,
  "ipAddress": null,
  "rootPassword": "generated_password"
}

---

5. Start Server

POST /server/:id/start

Starts a stopped server.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "success",
  "action": "start",
  "taskId": "UPID:..."
}

---

6. Stop Server

POST /server/:id/stop

Stops a running server.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "success",
  "action": "stop",
  "taskId": "UPID:..."
}

---

7. Restart Server

POST /server/:id/restart

Restarts a server.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "success",
  "action": "restart",
  "taskId": "UPID:..."
}

---

8. Delete Server

DELETE /server/:id

Permanently deletes a server and its container.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "deleted"
}

---

9. Change Root Password

POST /server/:id/password

Generates and sets a new root password for the server.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "success",
  "password": "new_generated_password"
}

---

10. Resize Server Configuration

PUT /server/:id/resize

Changes server resources (CPU, RAM, disk).

Parameters:

• id (path) - Server ID

Request Body:

{
  "cores": 4,
  "memory": 4096,
  "disk": 80
}

Note: All fields are optional. Only specified fields will be updated.

Response:

{
  "status": "success",
  "data": "..."
}

---

11. Create Snapshot

POST /server/:id/snapshots

Creates a snapshot of the server's current state.

Parameters:

• id (path) - Server ID

Request Body:

{
  "snapname": "backup-2024-01-01",
  "description": "Before major update"
}

Response:

{
  "status": "success",
  "taskId": "UPID:...",
  "snapname": "backup-2024-01-01"
}

---

12. List Snapshots

GET /server/:id/snapshots

Returns a list of all snapshots for the server.

Parameters:

• id (path) - Server ID

Response:

{
  "status": "success",
  "data": [
    {
      "name": "backup-2024-01-01",
      "description": "Before major update",
      "snaptime": 1704067200
    }
  ]
}

---

13. Rollback Snapshot

POST /server/:id/snapshots/rollback

Restores the server to a previous snapshot state.

Parameters:

• id (path) - Server ID

Request Body:

{
  "snapname": "backup-2024-01-01"
}

Response:

{
  "status": "success",
  "taskId": "UPID:..."
}

---

14. Delete Snapshot

DELETE /server/:id/snapshots

Deletes a specific snapshot.

Parameters:

• id (path) - Server ID

Request Body:

{
  "snapname": "backup-2024-01-01"
}

Response:

{
  "status": "success",
  "taskId": "UPID:..."
}

---

15. Get Console Access

POST /server/console

Returns a URL for accessing the server console via noVNC.

Request Body:

{
  "vmid": 100
}

Response:

{
  "status": "success",
  "url": "https://proxmox.example.com/?console=lxc&vmid=100&node=proxmox&ticket=..."
}

---

WebSocket Events

Connection

Connect to http://localhost:5000 with Socket.IO client.

Subscribe to Server Updates

socket.emit('subscribe-server', serverId);

Unsubscribe from Server Updates

socket.emit('unsubscribe-server', serverId);

Receive Server Statistics

socket.on('server-stats', (data) => {
  console.log(data);
  // {
  //   serverId: 1,
  //   stats: { ... }
  // }
});

Receive Server Alerts

socket.on('server-alerts', (data) => {
  console.log(data);
  // {
  //   serverId: 1,
  //   alerts: [
  //     { type: 'cpu', message: 'CPU usage is at 95%', level: 'warning' }
  //   ]
  // }
});

---

Error Responses

All endpoints may return error responses in the following format:

{
  "error": "Error message description"
}

Common HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid or missing token)
• 404 - Not Found (resource doesn't exist)
• 500 - Internal Server Error

---

Email Notifications

The system automatically sends email notifications for:

• Server creation
• Resource usage alerts (CPU/Memory/Disk > 90%)
• Payment reminders
• Support ticket responses

Email notifications require SMTP configuration in .env:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

---

Monitoring Service

The monitoring service runs automatically and:

• Checks all servers every 30 seconds
• Updates database with current metrics
• Broadcasts real-time updates via WebSocket
• Sends alerts when resource usage exceeds 90%
• Sends email notifications for critical alerts

---

Best Practices

1. Resource Management: Always check server status before performing actions (start/stop/restart)
2. Snapshots: Create snapshots before major changes or updates
3. Monitoring: Subscribe to WebSocket updates for real-time monitoring
4. Error Handling: Always handle potential errors from API calls
5. Authentication: Store and refresh access tokens securely
6. Rate Limiting: Avoid excessive API calls; use WebSocket for real-time data

---

Example Usage

JavaScript/TypeScript Example

import axios from 'axios';
import { io } from 'socket.io-client';

const API_URL = 'http://localhost:5000/api';
const token = localStorage.getItem('access_token');

// Get server status
const getServerStatus = async (serverId: number) => {
  const response = await axios.get(
    `${API_URL}/server/${serverId}/status`,
    {
      headers: { Authorization: `Bearer ${token}` }
    }
  );
  return response.data;
};

// Subscribe to real-time updates
const socket = io('http://localhost:5000');
socket.emit('subscribe-server', 1);
socket.on('server-stats', (data) => {
  console.log('Real-time stats:', data);
});

// Create snapshot
const createSnapshot = async (serverId: number) => {
  const response = await axios.post(
    `${API_URL}/server/${serverId}/snapshots`,
    {
      snapname: `backup-${Date.now()}`,
      description: 'Automatic backup'
    },
    {
      headers: { Authorization: `Bearer ${token}` }
    }
  );
  return response.data;
};

---

Last updated: 2024 Version: 8.1