API Reference¶

Comprehensive documentation for the VPN Exit Controller REST API.

API Overview¶

The VPN Exit Controller API provides programmatic access to all system functions:

• RESTful Design: Clean, predictable URL structure
• JSON Format: All requests and responses use JSON
• HTTP Basic Auth: Simple, secure authentication
• Comprehensive: Full control over nodes, metrics, and configuration
• Well-Documented: OpenAPI/Swagger specification available

Quick Start¶

Base URL¶

https://api.vpn.yourdomain.com

Authentication¶

curl -u admin:password https://api.vpn.yourdomain.com/api/nodes

Example Request¶

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{"country": "us"}' \
  https://api.vpn.yourdomain.com/api/nodes/start

API Documentation¶

API Categories¶

Node Management¶

Control VPN nodes - start, stop, monitor

• GET /api/nodes - List all nodes
• POST /api/nodes/start - Start a node
• DELETE /api/nodes/{id} - Stop a node
• GET /api/nodes/{id}/health - Node health

Load Balancing¶

Configure and query load balancing

• GET /api/load-balancer/best-node/{country} - Get optimal node
• POST /api/load-balancer/strategy - Set strategy
• GET /api/load-balancer/status - Current status

Metrics & Monitoring¶

Access performance and health data

• GET /api/metrics - System metrics
• GET /api/health - Health check
• POST /api/speed-test/{id} - Run speed test

Configuration¶

Manage system configuration

• GET /api/config - Get configuration
• PUT /api/config - Update settings
• POST /api/config/reload - Reload config

Response Format¶

Success Response¶

{
  "status": "success",
  "data": {
    "id": "vpn-us-1",
    "country": "us",
    "status": "running"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response¶

{
  "status": "error",
  "error": {
    "code": "NODE_NOT_FOUND",
    "message": "No node with ID 'vpn-xyz' exists",
    "details": {}
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Status Codes¶

Rate Limiting¶

API requests are rate limited:

• Default: 100 requests/minute
• Burst: 20 requests/second
• Headers: Rate limit info included

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642257600

API Versioning¶

The API uses URL versioning:

• Current: /api/v1/ (or /api/)
• Legacy: Not applicable (v1 is first version)

OpenAPI Specification¶

Interactive API documentation available at:

• Swagger UI: https://api.vpn.yourdomain.com/api/docs
• ReDoc: https://api.vpn.yourdomain.com/api/redoc
• OpenAPI JSON: https://api.vpn.yourdomain.com/api/openapi.json

Quick Links¶

• Authentication Guide - Set up API access
• Complete Endpoint Reference - All endpoints documented
• Code Examples - Copy-paste examples
• SDK Documentation - Language-specific libraries