mvpg/docs/API.md

# 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