New branch

docs/API.md

@@ -0,0 +1,320 @@
+# API Reference
+
+## Overview
+
+The VPN Gateway provides a RESTful API for managing VPN connections and configuration.
+
+Base URL: `http://<gateway-ip>:5000`
+
+## Authentication
+
+Currently, the API does not require authentication for local network access. For production use, consider implementing API keys or JWT tokens.
+
+## Endpoints
+
+### System Status
+
+#### GET /api/status
+Get current VPN and system status.
+
+**Response:**
+```json
+{
+  "connected": true,
+  "provider": "mullvad",
+  "server": "se-sto-wg-001",
+  "ip": "185.65.134.123",
+  "location": "Stockholm, Sweden",
+  "uptime": "2h 34m",
+  "killswitch_active": true
+}
+```
+
+### Provider Management
+
+#### GET /api/providers
+List available providers.
+
+**Response:**
+```json
+{
+  "providers": ["mullvad", "custom", "imported"],
+  "current": "mullvad"
+}
+```
+
+#### POST /api/provider/{provider}
+Switch to a different provider.
+
+**Parameters:**
+- `provider`: Provider name (mullvad|custom|imported)
+
+**Response:**
+```json
+{
+  "success": true,
+  "provider": "custom"
+}
+```
+
+### Server Management
+
+#### GET /api/servers
+Get available servers for current provider.
+
+**Response:**
+```json
+{
+  "servers": {
+    "Sweden": {
+      "Stockholm": [
+        {
+          "hostname": "se-sto-wg-001",
+          "ipv4": "185.65.134.123",
+          "type": "WireGuard",
+          "provider": "Mullvad"
+        }
+      ]
+    }
+  },
+  "provider": "mullvad"
+}
+```
+
+### Connection Management
+
+#### POST /api/connect
+Connect to VPN server.
+
+**Request Body:**
+```json
+{
+  "server": "se-sto-wg-001"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+#### POST /api/disconnect
+Disconnect from VPN.
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Disconnected - No internet (killswitch active)"
+}
+```
+
+### Custom Server Management
+
+#### POST /api/custom/add
+Add a custom WireGuard server.
+
+**Request Body:**
+```json
+{
+  "name": "my-vps",
+  "endpoint": "1.2.3.4:51820",
+  "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
+  "private_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy=",
+  "address": "10.0.0.2/32",
+  "dns": "1.1.1.1,1.0.0.1",
+  "allowed_ips": "0.0.0.0/0,::/0",
+  "location": "Germany"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+#### DELETE /api/custom/remove/{name}
+Remove a custom server.
+
+**Parameters:**
+- `name`: Server name
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+### Import Configuration
+
+#### POST /api/import
+Import a WireGuard configuration.
+
+**Request Body:**
+```json
+{
+  "name": "imported-config",
+  "config": "[Interface]\nPrivateKey = xxx\n..."
+}
+```
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+### Utility
+
+#### GET /api/keypair
+Generate a new WireGuard keypair.
+
+**Response:**
+```json
+{
+  "private_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
+  "public_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy="
+}
+```
+
+#### GET /health
+Health check endpoint.
+
+**Response:**
+```
+healthy
+```
+
+## Error Responses
+
+All endpoints may return error responses:
+
+```json
+{
+  "success": false,
+  "error": "Error message here"
+}
+```
+
+Common HTTP status codes:
+- `200`: Success
+- `400`: Bad request
+- `404`: Not found
+- `500`: Internal server error
+
+## WebSocket Events (Future)
+
+Planned WebSocket support for real-time updates:
+
+```javascript
+const ws = new WebSocket('ws://gateway-ip:5000/ws');
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Event:', data.type, data.payload);
+};
+```
+
+Events:
+- `status_change`: VPN connection status changed
+- `server_update`: Server list updated
+- `security_alert`: Security issue detected
+
+## Example Usage
+
+### cURL
+
+```bash
+# Get status
+curl http://gateway-ip:5000/api/status
+
+# Connect to server
+curl -X POST http://gateway-ip:5000/api/connect \
+  -H "Content-Type: application/json" \
+  -d '{"server":"se-sto-wg-001"}'
+
+# Add custom server
+curl -X POST http://gateway-ip:5000/api/custom/add \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-server",
+    "endpoint": "1.2.3.4:51820",
+    "public_key": "xxx..."
+  }'
+```
+
+### Python
+
+```python
+import requests
+
+# API base URL
+base_url = "http://gateway-ip:5000"
+
+# Get status
+response = requests.get(f"{base_url}/api/status")
+status = response.json()
+print(f"Connected: {status['connected']}")
+
+# Connect to server
+response = requests.post(
+    f"{base_url}/api/connect",
+    json={"server": "se-sto-wg-001"}
+)
+if response.json()["success"]:
+    print("Connected successfully")
+```
+
+### JavaScript
+
+```javascript
+// Get status
+fetch('http://gateway-ip:5000/api/status')
+  .then(response => response.json())
+  .then(data => console.log('Status:', data));
+
+// Connect to server
+fetch('http://gateway-ip:5000/api/connect', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    server: 'se-sto-wg-001'
+  })
+})
+.then(response => response.json())
+.then(data => {
+  if (data.success) {
+    console.log('Connected');
+  }
+});
+```
+
+## Rate Limiting
+
+API endpoints are rate-limited:
+- General endpoints: 10 requests/second
+- Connection endpoints: 5 requests/second
+
+Headers returned:
+- `X-RateLimit-Limit`: Request limit
+- `X-RateLimit-Remaining`: Remaining requests
+- `X-RateLimit-Reset`: Reset timestamp
+
+## Future Enhancements
+
+Planned API features:
+- JWT authentication
+- GraphQL endpoint
+- Metrics endpoint (Prometheus format)
+- Bulk operations
+- Configuration backup/restore
+- Traffic statistics
+- Connection history