Skip to content

README.md

Latest commit

 

History

History
637 lines (520 loc) · 10.1 KB

README.md

File metadata and controls

637 lines (520 loc) · 10.1 KB

API Reference

ShellUI provides a comprehensive REST API for integration with external systems, automation scripts, and custom applications.

Base URL

http://localhost:3000/api

Authentication

Most API endpoints require authentication. Include your authentication token in the request headers:

Authorization: Bearer <your-token>

Endpoints

Commands

Get All Commands

GET /api/commands

Response:

{
  "commands": [
    {
      "id": "system-info",
      "title": "System Information",
      "description": "Display system information",
      "icon": "Terminal",
      "category": "System",
      "shell": "/bin/bash",
      "command": "uname -a && df -h && free -h",
      "args": [],
      "timeout": 30000,
      "confirm": false,
      "hasHelp": true
    }
  ]
}

Execute Command

POST /api/commands/{id}/execute
Content-Type: application/json

{
  "args": {
    "host": "google.com",
    "count": 4
  }
}

Response:

{
  "executionId": "uuid-here",
  "status": "started",
  "message": "Command execution started"
}

Validate Command Arguments

GET /api/commands/validate-args/{id}?host=google.com&count=4

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "command": {
    "id": "ping-test",
    "title": "Ping Test",
    "description": "Test network connectivity",
    "args": [...]
  }
}

Get Command Help

GET /api/commands/{id}/help

Response:

{
  "commandId": "system-info",
  "helpOutput": "Usage: uname [OPTION]...\nPrint certain system information...",
  "available": true,
  "generatedAt": "2024-01-01T12:00:00.000Z"
}

Bulk Help

GET /api/commands/bulk-help

Response:

[
  {
    "commandId": "system-info",
    "helpOutput": "Usage: uname [OPTION]...",
    "available": true,
    "generatedAt": "2024-01-01T12:00:00.000Z"
  }
]

Executions

Get Execution History

GET /api/history

Query Parameters:

  • limit (number): Number of executions to return (default: 50)
  • offset (number): Number of executions to skip (default: 0)
  • commandId (string): Filter by command ID
  • status (string): Filter by status (running, success, error)
  • from (string): Filter by start date (ISO format)
  • to (string): Filter by end date (ISO format)

Response:

{
  "executions": [
    {
      "id": "uuid-here",
      "commandId": "ping-test",
      "status": "success",
      "output": "PING google.com (142.250.190.78) 56(84) bytes of data...",
      "error": "",
      "args": {
        "host": "google.com",
        "count": 4
      },
      "startedAt": "2024-01-01T12:00:00.000Z",
      "finishedAt": "2024-01-01T12:00:01.000Z",
      "duration": 1000,
      "exitCode": 0
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Get Execution by ID

GET /api/history/{executionId}

Response:

{
  "id": "uuid-here",
  "commandId": "ping-test",
  "status": "success",
  "output": "PING google.com (142.250.190.78) 56(84) bytes of data...",
  "error": "",
  "args": {
    "host": "google.com",
    "count": 4
  },
  "startedAt": "2024-01-01T12:00:00.000Z",
  "finishedAt": "2024-01-01T12:00:01.000Z",
  "duration": 1000,
  "exitCode": 0
}

Delete Execution

DELETE /api/history/{executionId}

Response:

{
  "success": true,
  "message": "Execution deleted successfully"
}

Get Executions by Command

GET /api/history/command/{commandId}

Response:

{
  "executions": [
    {
      "id": "uuid-here",
      "commandId": "ping-test",
      "status": "success",
      "output": "...",
      "startedAt": "2024-01-01T12:00:00.000Z",
      "finishedAt": "2024-01-01T12:00:01.000Z"
    }
  ]
}

Statistics

Get Execution Statistics

GET /api/history/stats

Response:

{
  "total": 1000,
  "successful": 950,
  "failed": 50,
  "running": 0,
  "averageDuration": 2500,
  "mostExecuted": [
    {
      "commandId": "system-info",
      "count": 150
    },
    {
      "commandId": "ping-test",
      "count": 120
    }
  ],
  "storage": {
    "initialized": true,
    "file": "data/executions.json"
  }
}

Configuration

Get Configuration

GET /api/config

Response:

{
  "title": "ShellUI - My Server",
  "version": "1.0.0",
  "description": "Modern web interface for server management",
  "theme": "dark",
  "features": {
    "auto_help": true,
    "show_command_help": true,
    "real_time_output": true,
    "command_history": true
  },
  "commands": [...]
}

Reload Configuration

POST /api/config/reload

Response:

{
  "success": true,
  "message": "Configuration reloaded successfully",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Get Configuration Status

GET /api/config/status

Response:

{
  "loaded": true,
  "lastModified": "2024-01-01T12:00:00.000Z",
  "path": "/etc/shellui/config.yaml",
  "valid": true,
  "errors": []
}

WebSocket Status

Get WebSocket Status

GET /api/commands/ws-status

Response:

{
  "enabled": true,
  "connections": 5,
  "maxConnections": 100,
  "path": "/ws",
  "pingInterval": 30000,
  "pingTimeout": 5000
}

Health Check

Health Status

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "uptime": 3600,
  "version": "1.0.0",
  "services": {
    "api": "ok",
    "websocket": "ok",
    "storage": "ok"
  }
}

WebSocket API

Connection

Connect to WebSocket endpoint:

const ws = new WebSocket('ws://localhost:3000/ws');

Message Types

Subscribe to Execution

{
  "type": "subscribe",
  "executionId": "uuid-here"
}

Unsubscribe from Execution

{
  "type": "unsubscribe",
  "executionId": "uuid-here"
}

Incoming Messages

Command Started

{
  "type": "command_started",
  "executionId": "uuid-here",
  "commandId": "ping-test",
  "command": "ping -c 4 google.com",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Output Data

{
  "type": "output",
  "executionId": "uuid-here",
  "data": "PING google.com (142.250.190.78) 56(84) bytes of data.\n",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Error Data

{
  "type": "error",
  "executionId": "uuid-here",
  "data": "ping: unknown host example.com\n",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Command Completed

{
  "type": "complete",
  "executionId": "uuid-here",
  "status": "success",
  "exitCode": 0,
  "duration": 1000,
  "timestamp": "2024-01-01T12:00:01.000Z"
}

Error Responses

Validation Error

{
  "error": "Validation failed",
  "details": [
    "Host is required",
    "Count must be at least 1"
  ],
  "warnings": [
    "Invalid regex pattern for host"
  ]
}

Not Found Error

{
  "error": "Command not found"
}

Server Error

{
  "error": "Internal server error",
  "message": "Failed to execute command"
}

Rate Limiting

API endpoints are rate-limited to prevent abuse. Limits are configured in the configuration file:

api:
  rateLimit:
    enabled: true
    windowMs: 900000  # 15 minutes
    maxRequests: 1000

When rate limit is exceeded:

{
  "error": "Too many requests",
  "retryAfter": 900
}

Authentication

Local Authentication

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

Response:

{
  "token": "jwt-token-here",
  "user": {
    "username": "admin",
    "roles": ["admin"],
    "permissions": ["execute:*", "configure:*", "view:*"]
  }
}

JWT Authentication

Include the JWT token in the Authorization header:

Authorization: Bearer <jwt-token>

Examples

Execute Command with cURL

# Execute ping command
curl -X POST http://localhost:3000/api/commands/ping-test/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "args": {
      "host": "google.com",
      "count": 4
    }
  }'

# Get execution history
curl http://localhost:3000/api/history?limit=10 \
  -H "Authorization: Bearer <token>"

JavaScript Example

// Execute command
const response = await fetch('/api/commands/ping-test/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    args: {
      host: 'google.com',
      count: 4
    }
  })
});

const result = await response.json();
console.log('Execution ID:', result.executionId);

// Subscribe to WebSocket updates
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    executionId: result.executionId
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'output') {
    console.log('Output:', message.data);
  } else if (message.type === 'complete') {
    console.log('Completed with status:', message.status);
  }
};

Python Example

import requests
import json

# Execute command
response = requests.post(
    'http://localhost:3000/api/commands/ping-test/execute',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <token>'
    },
    json={
        'args': {
            'host': 'google.com',
            'count': 4
        }
    }
)

result = response.json()
print('Execution ID:', result['executionId'])

# Get execution history
history = requests.get(
    'http://localhost:3000/api/history',
    headers={'Authorization': 'Bearer <token>'}
)

executions = history.json()['executions']
for execution in executions:
    print(f"{execution['commandId']}: {execution['status']}")

SDK Libraries

Official SDK libraries are available for popular programming languages:

  • JavaScript/TypeScript: @shellui/sdk
  • Python: shellui-sdk
  • Go: github.com/shellui/sdk
  • Rust: shellui-sdk

See the SDK Documentation for detailed usage examples.