Documentation > API Reference > Configuration API

Configuration API

System configuration management and settings through programmatic interfaces for comprehensive system control.

Overview

The Configuration API provides comprehensive access to system settings, feature toggles, environment-specific configurations, and administrative preferences. It enables dynamic configuration management without requiring system restarts for most settings.

Base URL

/api/v1/configuration

Authentication

All endpoints require valid JWT authentication with administrative privileges for most write operations.

Configuration Categories

System Settings

  • Database Configuration: Connection settings and performance tuning
  • Authentication Settings: JWT, session, and security configurations
  • Network Configuration: Ports, SSL/TLS, and communication settings
  • Logging Configuration: Log levels, retention, and output settings

Agent Management

  • Agent Communication: Heartbeat intervals and timeouts
  • Data Collection: Metric collection frequencies and retention
  • Security Settings: Certificate validation and mTLS configuration
  • Auto-approval Rules: Automatic agent approval criteria

Feature Toggles

  • Experimental Features: Beta feature enablement
  • Module Control: Enable/disable specific modules
  • API Endpoints: Selective API endpoint availability
  • UI Components: Frontend feature control

Performance Settings

  • Cache Configuration: Redis and application cache settings
  • Queue Management: Background job and message queue tuning
  • Rate Limiting: API rate limits and throttling
  • Resource Limits: Memory, CPU, and storage limits

API Endpoints

Get All Configuration

GET /api/v1/configuration

Retrieve all configuration settings organized by category.

Query Parameters

  • category - Filter by configuration category
  • include_sensitive - Include sensitive values (admin only)
  • format - Response format: json, yaml (default: json)

Request

GET /api/v1/configuration?category=system&include_sensitive=false
Authorization: Bearer {jwt_token}

Response

{
  "configuration": {
    "system": {
      "application": {
        "name": "SysManage",
        "version": "1.0.0",
        "environment": "production",
        "debug_mode": false,
        "maintenance_mode": false
      },
      "database": {
        "host": "localhost",
        "port": 5432,
        "name": "sysmanage",
        "pool_size": 10,
        "timeout": 30,
        "ssl_mode": "require"
      },
      "authentication": {
        "jwt_expiry": 3600,
        "refresh_token_expiry": 604800,
        "max_login_attempts": 5,
        "lockout_duration": 900,
        "mfa_required": false,
        "password_policy": {
          "min_length": 12,
          "require_uppercase": true,
          "require_lowercase": true,
          "require_numbers": true,
          "require_special": true,
          "max_age_days": 90
        }
      },
      "network": {
        "listen_address": "0.0.0.0",
        "listen_port": 8443,
        "ssl_enabled": true,
        "ssl_cert_path": "/opt/sysmanage/ssl/server.crt",
        "ssl_key_path": "/opt/sysmanage/ssl/server.key",
        "cors_enabled": true,
        "cors_origins": ["*"]
      }
    },
    "agents": {
      "communication": {
        "heartbeat_interval": 60,
        "timeout": 300,
        "max_retries": 3,
        "retry_delay": 5
      },
      "data_collection": {
        "metrics_interval": 60,
        "package_scan_interval": 3600,
        "system_info_interval": 86400,
        "log_collection": true
      },
      "security": {
        "require_mtls": true,
        "cert_validation": "strict",
        "allowed_cipher_suites": [
          "TLS_AES_256_GCM_SHA384",
          "TLS_CHACHA20_POLY1305_SHA256"
        ]
      },
      "auto_approval": {
        "enabled": false,
        "criteria": {
          "trusted_networks": ["192.168.1.0/24"],
          "known_hostnames": ["*.example.com"],
          "max_auto_approvals_per_hour": 10
        }
      }
    }
  },
  "metadata": {
    "retrieved_at": "2024-01-15T11:15:00Z",
    "categories_included": ["system", "agents"],
    "sensitive_data_included": false,
    "total_settings": 47
  }
}

Get Configuration Category

GET /api/v1/configuration/{category}

Retrieve configuration settings for a specific category.

Request

GET /api/v1/configuration/features
Authorization: Bearer {jwt_token}

Response

{
  "category": "features",
  "configuration": {
    "experimental": {
      "advanced_analytics": false,
      "ai_anomaly_detection": false,
      "automated_remediation": false,
      "custom_dashboards": true
    },
    "modules": {
      "package_management": true,
      "user_management": true,
      "reporting": true,
      "api_access": true,
      "webhook_integration": true,
      "ldap_integration": false
    },
    "api_endpoints": {
      "v1_enabled": true,
      "v2_enabled": false,
      "deprecated_endpoints": false,
      "rate_limiting": true
    },
    "ui_components": {
      "dark_mode": true,
      "real_time_updates": true,
      "advanced_filters": true,
      "bulk_operations": true,
      "mobile_responsive": true
    }
  },
  "metadata": {
    "category": "features",
    "total_settings": 16,
    "last_modified": "2024-01-10T15:30:00Z",
    "modified_by": "admin"
  }
}

Update Configuration

PUT /api/v1/configuration/{category}

Update configuration settings for a specific category.

Request

PUT /api/v1/configuration/agents
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "communication": {
    "heartbeat_interval": 30,
    "timeout": 180
  },
  "data_collection": {
    "metrics_interval": 30,
    "package_scan_interval": 1800
  },
  "auto_approval": {
    "enabled": true,
    "criteria": {
      "trusted_networks": ["192.168.1.0/24", "10.0.0.0/8"],
      "max_auto_approvals_per_hour": 20
    }
  }
}

Response

{
  "category": "agents",
  "status": "updated",
  "updated_at": "2024-01-15T11:20:00Z",
  "changes": [
    {
      "setting": "communication.heartbeat_interval",
      "old_value": 60,
      "new_value": 30
    },
    {
      "setting": "communication.timeout",
      "old_value": 300,
      "new_value": 180
    },
    {
      "setting": "data_collection.metrics_interval",
      "old_value": 60,
      "new_value": 30
    },
    {
      "setting": "auto_approval.enabled",
      "old_value": false,
      "new_value": true
    }
  ],
  "restart_required": false,
  "agents_notified": 25
}

Get Single Setting

GET /api/v1/configuration/{category}/{setting}

Retrieve a specific configuration setting.

Request

GET /api/v1/configuration/system/authentication
Authorization: Bearer {jwt_token}

Response

{
  "category": "system",
  "setting": "authentication",
  "value": {
    "jwt_expiry": 3600,
    "refresh_token_expiry": 604800,
    "max_login_attempts": 5,
    "lockout_duration": 900,
    "mfa_required": false,
    "password_policy": {
      "min_length": 12,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_special": true,
      "max_age_days": 90
    }
  },
  "metadata": {
    "data_type": "object",
    "last_modified": "2024-01-01T00:00:00Z",
    "modified_by": "system",
    "description": "Authentication and security settings",
    "restart_required": false
  }
}

Update Single Setting

PUT /api/v1/configuration/{category}/{setting}

Update a specific configuration setting.

Request

PUT /api/v1/configuration/features/experimental
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "value": {
    "advanced_analytics": true,
    "ai_anomaly_detection": false,
    "automated_remediation": false,
    "custom_dashboards": true
  }
}

Response

{
  "category": "features",
  "setting": "experimental",
  "status": "updated",
  "updated_at": "2024-01-15T11:25:00Z",
  "old_value": {
    "advanced_analytics": false,
    "ai_anomaly_detection": false,
    "automated_remediation": false,
    "custom_dashboards": true
  },
  "new_value": {
    "advanced_analytics": true,
    "ai_anomaly_detection": false,
    "automated_remediation": false,
    "custom_dashboards": true
  },
  "restart_required": false,
  "affected_components": ["analytics_engine", "reporting_module"]
}

Validate Configuration

POST /api/v1/configuration/validate

Validate configuration changes before applying them.

Request

POST /api/v1/configuration/validate
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "category": "system",
  "settings": {
    "database": {
      "host": "new-db-server.example.com",
      "port": 5432,
      "pool_size": 20,
      "timeout": 60
    },
    "network": {
      "listen_port": 9443,
      "ssl_enabled": true
    }
  }
}

Response

{
  "validation_result": "success",
  "validated_at": "2024-01-15T11:30:00Z",
  "settings_validated": 6,
  "warnings": [
    {
      "setting": "database.timeout",
      "message": "High timeout value may impact performance",
      "severity": "warning",
      "recommendation": "Consider values between 10-30 seconds"
    }
  ],
  "errors": [],
  "compatibility_check": {
    "database_connection": "success",
    "port_availability": "success",
    "ssl_certificate": "success"
  },
  "estimated_impact": {
    "restart_required": true,
    "affected_agents": 25,
    "downtime_estimate": "30-60 seconds"
  }
}

Reset Configuration

POST /api/v1/configuration/{category}/reset

Reset configuration category to default values.

Request

POST /api/v1/configuration/features/reset
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "confirm": true,
  "backup": true,
  "settings": ["experimental", "ui_components"]
}

Response

{
  "category": "features",
  "status": "reset",
  "reset_at": "2024-01-15T11:35:00Z",
  "backup_created": true,
  "backup_id": "backup_20240115_113500",
  "settings_reset": [
    "experimental",
    "ui_components"
  ],
  "changes": [
    {
      "setting": "experimental.advanced_analytics",
      "old_value": true,
      "new_value": false
    },
    {
      "setting": "ui_components.dark_mode",
      "old_value": true,
      "new_value": false
    }
  ],
  "restart_required": false
}

Export Configuration

GET /api/v1/configuration/export

Export configuration in various formats for backup or migration.

Query Parameters

  • format - Export format: json, yaml, toml (default: json)
  • categories - Comma-separated list of categories to export
  • include_sensitive - Include sensitive values (default: false)
  • include_metadata - Include metadata (default: true)

Request

GET /api/v1/configuration/export?format=yaml&categories=system,agents
Authorization: Bearer {jwt_token}

Response (YAML format)

Content-Type: application/x-yaml
Content-Disposition: attachment; filename="sysmanage_config_20240115.yaml"

metadata:
  exported_at: "2024-01-15T11:40:00Z"
  exported_by: "admin"
  version: "1.0.0"
  categories: ["system", "agents"]

configuration:
  system:
    application:
      name: "SysManage"
      version: "1.0.0"
      environment: "production"
      debug_mode: false
    database:
      host: "localhost"
      port: 5432
      name: "sysmanage"
      pool_size: 10
  agents:
    communication:
      heartbeat_interval: 30
      timeout: 180
    data_collection:
      metrics_interval: 30
      package_scan_interval: 1800

Import Configuration

POST /api/v1/configuration/import

Import configuration from backup or external source.

Request

POST /api/v1/configuration/import
Authorization: Bearer {jwt_token}
Content-Type: multipart/form-data

file: [configuration_file.yaml]
options: {
  "validate_before_import": true,
  "create_backup": true,
  "merge_strategy": "overwrite",
  "categories": ["system", "features"]
}

Response

{
  "import_result": "success",
  "imported_at": "2024-01-15T11:45:00Z",
  "backup_created": true,
  "backup_id": "backup_20240115_114500",
  "validation_result": "passed",
  "categories_imported": ["system", "features"],
  "settings_changed": 12,
  "settings_added": 3,
  "settings_removed": 1,
  "changes_summary": [
    {
      "category": "system",
      "setting": "database.pool_size",
      "action": "updated",
      "old_value": 10,
      "new_value": 15
    },
    {
      "category": "features",
      "setting": "experimental.new_feature",
      "action": "added",
      "new_value": true
    }
  ],
  "restart_required": true,
  "affected_components": ["database", "analytics_engine"]
}

Configuration Schema

GET /api/v1/configuration/schema

Get the configuration schema with validation rules and descriptions.

Query Parameters

  • category - Get schema for specific category
  • format - Schema format: json-schema, openapi (default: json-schema)

Request

GET /api/v1/configuration/schema?category=system
Authorization: Bearer {jwt_token}

Response

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "System Configuration Schema",
    "properties": {
      "application": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Application name"
          },
          "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$",
            "description": "Application version (semantic versioning)"
          },
          "environment": {
            "type": "string",
            "enum": ["development", "staging", "production"],
            "description": "Deployment environment"
          },
          "debug_mode": {
            "type": "boolean",
            "description": "Enable debug logging and features"
          }
        },
        "required": ["name", "version", "environment"]
      },
      "database": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "description": "Database server hostname"
          },
          "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535,
            "description": "Database server port"
          },
          "pool_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Connection pool size"
          }
        },
        "required": ["host", "port"]
      }
    }
  },
  "metadata": {
    "category": "system",
    "version": "1.0.0",
    "last_updated": "2024-01-01T00:00:00Z"
  }
}

Environment-Specific Configuration

Get Environment Configuration

GET /api/v1/configuration/environments/{environment}

Retrieve configuration specific to an environment (development, staging, production).

Request

GET /api/v1/configuration/environments/production
Authorization: Bearer {jwt_token}

Response

{
  "environment": "production",
  "configuration": {
    "system": {
      "debug_mode": false,
      "log_level": "info",
      "maintenance_mode": false
    },
    "security": {
      "ssl_required": true,
      "mfa_required": true,
      "session_timeout": 3600
    },
    "performance": {
      "cache_enabled": true,
      "compression_enabled": true,
      "rate_limiting": true
    }
  },
  "overrides": {
    "database.pool_size": 20,
    "agents.heartbeat_interval": 60,
    "features.experimental": false
  },
  "metadata": {
    "environment": "production",
    "active": true,
    "last_deployed": "2024-01-10T15:00:00Z"
  }
}

Switch Environment

POST /api/v1/configuration/environments/switch

Switch to a different environment configuration.

Request

POST /api/v1/configuration/environments/switch
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "target_environment": "staging",
  "confirm": true,
  "create_backup": true
}

Response

{
  "status": "environment_switched",
  "from_environment": "production",
  "to_environment": "staging",
  "switched_at": "2024-01-15T11:50:00Z",
  "backup_created": true,
  "backup_id": "env_backup_20240115_115000",
  "configuration_changes": 15,
  "restart_required": true,
  "estimated_downtime": "60-120 seconds"
}

Error Handling

Common Error Responses

400 Bad Request

{
  "error": "invalid_configuration",
  "message": "Configuration validation failed",
  "validation_errors": [
    {
      "setting": "database.pool_size",
      "error": "Value must be between 1 and 100",
      "provided_value": 150
    }
  ]
}

403 Forbidden

{
  "error": "insufficient_permissions",
  "message": "User does not have permission to modify system configuration",
  "required_permission": "system_configuration"
}

404 Not Found

{
  "error": "configuration_not_found",
  "message": "Configuration category 'invalid_category' not found",
  "category": "invalid_category",
  "available_categories": ["system", "agents", "features", "performance"]
}

422 Unprocessable Entity

{
  "error": "configuration_conflict",
  "message": "Configuration change would create system conflict",
  "conflicts": [
    {
      "setting": "network.listen_port",
      "conflict": "Port already in use by another service",
      "current_value": 8443,
      "requested_value": 8080
    }
  ]
}

Code Examples

Python Example - Configuration Management

import requests
import yaml

class SysManageConfig:
    def __init__(self, api_base, token):
        self.api_base = api_base
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def get_configuration(self, category=None):
        """Get configuration for all categories or specific category"""
        url = f'{self.api_base}/configuration'
        if category:
            url += f'/{category}'

        response = requests.get(url, headers=self.headers)

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Failed to get configuration: {response.text}")

    def update_configuration(self, category, settings):
        """Update configuration for a specific category"""
        # First validate the configuration
        validation_response = requests.post(
            f'{self.api_base}/configuration/validate',
            headers=self.headers,
            json={'category': category, 'settings': settings}
        )

        if validation_response.status_code != 200:
            raise Exception(f"Configuration validation failed: {validation_response.text}")

        validation_result = validation_response.json()

        if validation_result['validation_result'] != 'success':
            print("Validation warnings:")
            for warning in validation_result.get('warnings', []):
                print(f"  - {warning['setting']}: {warning['message']}")

            if validation_result.get('errors'):
                raise Exception("Configuration has validation errors")

        # Apply the configuration
        response = requests.put(
            f'{self.api_base}/configuration/{category}',
            headers=self.headers,
            json=settings
        )

        if response.status_code == 200:
            result = response.json()
            print(f"Configuration updated successfully")
            print(f"Changes: {len(result['changes'])}")

            if result.get('restart_required'):
                print("⚠️  System restart required for changes to take effect")

            return result
        else:
            raise Exception(f"Failed to update configuration: {response.text}")

    def export_configuration(self, filename, format='yaml', categories=None):
        """Export configuration to file"""
        params = {'format': format}
        if categories:
            params['categories'] = ','.join(categories)

        response = requests.get(
            f'{self.api_base}/configuration/export',
            headers=self.headers,
            params=params
        )

        if response.status_code == 200:
            with open(filename, 'w') as f:
                if format == 'yaml':
                    f.write(response.text)
                else:
                    f.write(response.text)

            print(f"Configuration exported to {filename}")
        else:
            raise Exception(f"Failed to export configuration: {response.text}")

    def toggle_feature(self, feature_name, enabled):
        """Toggle a specific feature on/off"""
        current_config = self.get_configuration('features')
        features = current_config['configuration']

        # Navigate to the feature setting
        feature_path = feature_name.split('.')
        setting = features
        for path_part in feature_path[:-1]:
            setting = setting[path_part]

        setting[feature_path[-1]] = enabled

        return self.update_configuration('features', features)

# Usage example
api_base = "https://your-server.example.com/api/v1"
token = "your_jwt_token_here"

config_manager = SysManageConfig(api_base, token)

# Get current agent configuration
agent_config = config_manager.get_configuration('agents')
print("Current agent heartbeat interval:",
      agent_config['configuration']['communication']['heartbeat_interval'])

# Update agent communication settings
new_agent_settings = {
    'communication': {
        'heartbeat_interval': 30,
        'timeout': 180,
        'max_retries': 5
    },
    'data_collection': {
        'metrics_interval': 30
    }
}

config_manager.update_configuration('agents', new_agent_settings)

# Toggle experimental features
config_manager.toggle_feature('experimental.advanced_analytics', True)
config_manager.toggle_feature('ui_components.dark_mode', True)

# Export configuration backup
config_manager.export_configuration('backup_config.yaml', 'yaml')

JavaScript Example - Dynamic Configuration Updates

class ConfigurationManager {
    constructor(apiBase, token) {
        this.apiBase = apiBase;
        this.headers = {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json'
        };
    }

    async getConfiguration(category = null) {
        const url = category
            ? `${this.apiBase}/configuration/${category}`
            : `${this.apiBase}/configuration`;

        const response = await fetch(url, { headers: this.headers });

        if (!response.ok) {
            throw new Error(`Failed to get configuration: ${response.statusText}`);
        }

        return await response.json();
    }

    async updateSetting(category, setting, value) {
        // Get current configuration
        const currentConfig = await this.getConfiguration(category);

        // Update the specific setting
        const settingPath = setting.split('.');
        let configSection = currentConfig.configuration;

        for (let i = 0; i < settingPath.length - 1; i++) {
            configSection = configSection[settingPath[i]];
        }

        configSection[settingPath[settingPath.length - 1]] = value;

        // Validate before applying
        const validation = await this.validateConfiguration(category, currentConfig.configuration);

        if (validation.validation_result !== 'success') {
            console.warn('Configuration validation warnings:', validation.warnings);

            if (validation.errors && validation.errors.length > 0) {
                throw new Error('Configuration validation failed');
            }
        }

        // Apply the configuration
        const response = await fetch(`${this.apiBase}/configuration/${category}`, {
            method: 'PUT',
            headers: this.headers,
            body: JSON.stringify(currentConfig.configuration)
        });

        if (!response.ok) {
            throw new Error(`Failed to update configuration: ${response.statusText}`);
        }

        return await response.json();
    }

    async validateConfiguration(category, settings) {
        const response = await fetch(`${this.apiBase}/configuration/validate`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ category, settings })
        });

        if (!response.ok) {
            throw new Error(`Validation failed: ${response.statusText}`);
        }

        return await response.json();
    }

    async getConfigurationSchema(category = null) {
        const url = category
            ? `${this.apiBase}/configuration/schema?category=${category}`
            : `${this.apiBase}/configuration/schema`;

        const response = await fetch(url, { headers: this.headers });

        if (!response.ok) {
            throw new Error(`Failed to get schema: ${response.statusText}`);
        }

        return await response.json();
    }

    async monitorConfigurationChanges(callback) {
        // Set up WebSocket connection for real-time configuration updates
        const wsUrl = this.apiBase.replace('http', 'ws') + '/configuration/changes';
        const ws = new WebSocket(wsUrl, [], {
            headers: { 'Authorization': this.headers.Authorization }
        });

        ws.onmessage = (event) => {
            const change = JSON.parse(event.data);
            callback(change);
        };

        ws.onerror = (error) => {
            console.error('Configuration monitoring error:', error);
        };

        return ws;
    }
}

// Usage example
const apiBase = 'https://your-server.example.com/api/v1';
const token = 'your_jwt_token_here';
const configManager = new ConfigurationManager(apiBase, token);

// Update agent heartbeat interval
configManager.updateSetting('agents', 'communication.heartbeat_interval', 45)
    .then(result => {
        console.log('Heartbeat interval updated:', result);

        if (result.restart_required) {
            console.log('⚠️  System restart required');
        }
    })
    .catch(error => {
        console.error('Failed to update setting:', error);
    });

// Monitor configuration changes in real-time
configManager.monitorConfigurationChanges((change) => {
    console.log('Configuration changed:', {
        category: change.category,
        setting: change.setting,
        oldValue: change.old_value,
        newValue: change.new_value,
        changedBy: change.changed_by,
        timestamp: change.timestamp
    });

    // Update UI to reflect changes
    updateConfigurationUI(change);
});

// Get configuration schema for form validation
configManager.getConfigurationSchema('system')
    .then(schema => {
        console.log('System configuration schema:', schema);
        // Use schema to build dynamic configuration forms
        buildConfigurationForm(schema);
    });

Quick Navigation

← User Management API Administration →