Admin UI REST API

This document provides comprehensive documentation for the MockForge Admin UI REST API endpoints.

Overview

The MockForge Admin UI provides a web-based interface for managing and monitoring MockForge servers. The API is organized around the following main areas:

Dashboard: System overview and real-time metrics
Server Management: Control and monitor server instances
Configuration: Update latency, faults, proxy, and validation settings
Logging: View and filter request logs
Metrics: Performance monitoring and analytics
Fixtures: Manage mock data and fixtures
Environment: Environment variable management

Base URL

All API endpoints are prefixed with /__mockforge to avoid conflicts with user-defined routes.

Authentication

Currently, the API does not implement authentication. In production deployments, consider adding authentication middleware.

Response Format

All API responses follow a consistent format:

{
  "success": boolean,
  "data": object | array | null,
  "error": string | null,
  "timestamp": string
}

Success Response

{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2025-09-17T10:30:00Z"
}

Error Response

{
  "success": false,
  "data": null,
  "error": "Error message",
  "timestamp": "2025-09-17T10:30:00Z"
}

API Endpoints

Dashboard

GET `/__mockforge/dashboard`

Get comprehensive dashboard data including system information, server status, routes, and recent logs.

Response:

{
  "success": true,
  "data": {
    "system": {
      "version": "0.1.0",
      "uptime_seconds": 3600,
      "memory_usage_mb": 128,
      "cpu_usage_percent": 15.5,
      "active_threads": 8,
      "total_routes": 25,
      "total_fixtures": 150
    },
    "servers": [
      {
        "server_type": "HTTP",
        "address": "127.0.0.1:3000",
        "running": true,
        "start_time": "2025-09-17T09:30:00Z",
        "uptime_seconds": 3600,
        "active_connections": 5,
        "total_requests": 1250
      }
    ],
    "routes": [
      {
        "method": "GET",
        "path": "/api/users",
        "priority": 0,
        "has_fixtures": true,
        "latency_ms": 45,
        "request_count": 125,
        "last_request": "2025-09-17T10:25:00Z",
        "error_count": 2
      }
    ],
    "recent_logs": [
      {
        "id": "log_1",
        "timestamp": "2025-09-17T10:29:00Z",
        "method": "GET",
        "path": "/api/users",
        "status_code": 200,
        "response_time_ms": 45,
        "client_ip": "127.0.0.1",
        "user_agent": "test-agent",
        "headers": {},
        "response_size_bytes": 1024,
        "error_message": null
      }
    ],
    "latency_profile": {
      "name": "default",
      "base_ms": 50,
      "jitter_ms": 20,
      "tag_overrides": {}
    },
    "fault_config": {
      "enabled": false,
      "failure_rate": 0.0,
      "status_codes": [500],
      "active_failures": 0
    },
    "proxy_config": {
      "enabled": false,
      "upstream_url": null,
      "timeout_seconds": 30,
      "requests_proxied": 0
    }
  }
}

Health Check

GET `/__mockforge/health`

Get system health status.

Response:

{
  "status": "healthy",
  "services": {
    "http": "healthy",
    "websocket": "healthy",
    "grpc": "healthy"
  },
  "last_check": "2025-09-17T10:30:00Z",
  "issues": []
}

Server Management

GET `/__mockforge/server-info`

Get information about server addresses and configuration.

Response:

{
  "success": true,
  "data": {
    "http_server": "127.0.0.1:3000",
    "ws_server": "127.0.0.1:3001",
    "grpc_server": "127.0.0.1:50051"
  }
}

POST `/__mockforge/servers/restart`

Initiate server restart.

Request Body:

{
  "reason": "Manual restart requested"
}

Response:

{
  "success": true,
  "data": {
    "message": "Server restart initiated. Please wait for completion."
  }
}

GET `/__mockforge/servers/restart/status`

Get restart status.

Response:

{
  "success": true,
  "data": {
    "in_progress": false,
    "initiated_at": null,
    "reason": null,
    "success": null
  }
}

Routes

GET `/__mockforge/routes`

Get information about configured routes (proxied to HTTP server).

Logs

GET `/__mockforge/logs`

Get request logs with optional filtering.

Query Parameters:

method (string): Filter by HTTP method
path (string): Filter by path pattern
status (number): Filter by status code
limit (number): Maximum number of results

Examples:

GET /__mockforge/logs?method=GET&limit=50
GET /__mockforge/logs?path=/api/users&status=200

Response:

{
  "success": true,
  "data": [
    {
      "id": "log_1",
      "timestamp": "2025-09-17T10:29:00Z",
      "method": "GET",
      "path": "/api/users",
      "status_code": 200,
      "response_time_ms": 45,
      "client_ip": "127.0.0.1",
      "user_agent": "test-agent",
      "headers": {},
      "response_size_bytes": 1024,
      "error_message": null
    }
  ]
}

POST `/__mockforge/logs/clear`

Clear all request logs.

Response:

{
  "success": true,
  "data": {
    "message": "Logs cleared"
  }
}

Metrics

GET `/__mockforge/metrics`

Get performance metrics and analytics.

Response:

{
  "success": true,
  "data": {
    "requests_by_endpoint": {
      "GET /api/users": 125,
      "POST /api/users": 45
    },
    "response_time_percentiles": {
      "p50": 45,
      "p95": 120,
      "p99": 250
    },
    "error_rate_by_endpoint": {
      "GET /api/users": 0.02,
      "POST /api/users": 0.0
    },
    "memory_usage_over_time": [
      ["2025-09-17T10:25:00Z", 120],
      ["2025-09-17T10:26:00Z", 125]
    ],
    "cpu_usage_over_time": [
      ["2025-09-17T10:25:00Z", 12.5],
      ["2025-09-17T10:26:00Z", 15.2]
    ]
  }
}

Configuration

GET `/__mockforge/config`

Get current configuration settings.

Response:

{
  "success": true,
  "data": {
    "latency": {
      "enabled": true,
      "base_ms": 50,
      "jitter_ms": 20,
      "tag_overrides": {}
    },
    "faults": {
      "enabled": false,
      "failure_rate": 0.0,
      "status_codes": [500, 502, 503]
    },
    "proxy": {
      "enabled": false,
      "upstream_url": null,
      "timeout_seconds": 30
    },
    "validation": {
      "mode": "enforce",
      "aggregate_errors": true,
      "validate_responses": false,
      "overrides": {}
    }
  }
}

POST `/__mockforge/config/latency`

Update latency configuration.

Request Body:

{
  "config_type": "latency",
  "data": {
    "base_ms": 100,
    "jitter_ms": 50,
    "tag_overrides": {
      "auth": 200
    }
  }
}

POST `/__mockforge/config/faults`

Update fault injection configuration.

Request Body:

{
  "config_type": "faults",
  "data": {
    "enabled": true,
    "failure_rate": 0.1,
    "status_codes": [500, 502, 503]
  }
}

POST `/__mockforge/config/proxy`

Update proxy configuration.

Request Body:

{
  "config_type": "proxy",
  "data": {
    "enabled": true,
    "upstream_url": "http://api.example.com",
    "timeout_seconds": 60
  }
}

POST `/__mockforge/validation`

Update validation settings.

Request Body:

{
  "mode": "warn",
  "aggregate_errors": false,
  "validate_responses": true,
  "overrides": {
    "GET /health": "off"
  }
}

Environment Variables

GET `/__mockforge/env`

Get relevant environment variables.

Response:

{
  "success": true,
  "data": {
    "MOCKFORGE_LATENCY_ENABLED": "true",
    "MOCKFORGE_HTTP_PORT": "3000",
    "RUST_LOG": "info"
  }
}

POST `/__mockforge/env`

Update an environment variable (runtime only).

Request Body:

{
  "key": "MOCKFORGE_LOG_LEVEL",
  "value": "debug"
}

Response:

{
  "success": true,
  "data": {
    "message": "Environment variable MOCKFORGE_LOG_LEVEL updated to 'debug'. Note: This change is not persisted and will be lost on restart."
  }
}

Files

POST `/__mockforge/files/content`

Get file content.

Request Body:

{
  "file_path": "config.yaml",
  "file_type": "yaml"
}

Response:

{
  "success": true,
  "data": "http:\n  request_validation: \"enforce\"\n  aggregate_validation_errors: true\n"
}

POST `/__mockforge/files/save`

Save file content.

Request Body:

{
  "file_path": "config.yaml",
  "content": "http:\n  port: 9080\n"
}

Response:

{
  "success": true,
  "data": {
    "message": "File saved successfully"
  }
}

Fixtures

GET `/__mockforge/fixtures`

Get all fixtures with metadata.

Response:

{
  "success": true,
  "data": [
    {
      "id": "fixture_123",
      "protocol": "http",
      "method": "GET",
      "path": "/api/users",
      "saved_at": "2025-09-17T09:00:00Z",
      "file_size": 2048,
      "file_path": "http/get/api_users_123.json",
      "fingerprint": "abc123",
      "metadata": { ... }
    }
  ]
}

POST `/__mockforge/fixtures/delete`

Delete a fixture.

Request Body:

{
  "fixture_id": "fixture_123"
}

POST `/__mockforge/fixtures/delete-bulk`

Delete multiple fixtures.

Request Body:

{
  "fixture_ids": ["fixture_123", "fixture_456"]
}

Response:

{
  "success": true,
  "data": {
    "deleted_count": 2,
    "total_requested": 2,
    "errors": []
  }
}

GET `/__mockforge/fixtures/download?id=fixture_123`

Download a fixture file.

Response: Binary file download

Smoke Tests

GET `/__mockforge/smoke`

Get smoke test results.

GET `/__mockforge/smoke/run`

Run smoke tests against fixtures.

Response:

{
  "success": true,
  "data": {
    "message": "Smoke tests started. Check results in the smoke tests section."
  }
}

Error Codes

HTTP Status Codes

200 OK: Success
400 Bad Request: Invalid request parameters
404 Not Found: Endpoint or resource not found
500 Internal Server Error: Server error

Common Error Messages

"Invalid config type": Configuration update with invalid type
"Failed to load fixtures": Error reading fixture files
"Path traversal detected": Security violation in file paths
"Server restart already in progress": Attempted restart while one is running

Rate Limiting

Currently, no rate limiting is implemented. Consider adding rate limiting for production deployments.

CORS

The API includes CORS middleware allowing cross-origin requests from web applications.

WebSocket Support

The admin UI supports real-time updates through WebSocket connections for live monitoring of metrics and logs.

Examples

Complete Dashboard Fetch

const response = await fetch('/__mockforge/dashboard');
const data = await response.json();

if (data.success) {
  console.log('System uptime:', data.data.system.uptime_seconds);
  console.log('Active servers:', data.data.servers.length);
}

Update Latency Configuration

const response = await fetch('/__mockforge/config/latency', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    config_type: 'latency',
    data: {
      base_ms: 100,
      jitter_ms: 25
    }
  })
});

const result = await response.json();
console.log(result.data.message);

Filter Logs

const response = await fetch('/__mockforge/logs?method=GET&status=200&limit=100');
const data = await response.json();

data.data.forEach(log => {
  console.log(`${log.method} ${log.path} - ${log.status_code} (${log.response_time_ms}ms)`);
});

Development

Running Tests

# Run all tests
cargo test --package mockforge-ui

# Run integration tests
cargo test --package mockforge-ui --test integration

# Run smoke tests
cargo test --package mockforge-ui --test smoke

Building Documentation

# Generate API documentation
cargo doc --package mockforge-ui --open

Security Considerations

Input Validation: All inputs should be validated
Path Traversal: File operations prevent directory traversal
Rate Limiting: Consider implementing rate limiting
Authentication: Add authentication for production use
HTTPS: Use HTTPS in production
CORS: Properly configure CORS policies

Contributing

When adding new API endpoints:

Follow the established response format
Add comprehensive error handling
Include integration tests
Update this documentation
Ensure proper CORS and security measures

MockForge Documentation