calejocontrol
/
CalejoControl
1
0
Fork 0
Code Issues Pull Requests 4 Packages Projects Releases Wiki Activity
CalejoControl/docs/API_REFERENCE.md

12 KiB
Raw Blame History

Calejo Control Adapter - API Reference

Overview

The Calejo Control Adapter provides a comprehensive REST API for system management, monitoring, and control operations. All API endpoints require authentication and support role-based access control.

Base URL: http://localhost:8080/api/v1

Authentication

JWT Authentication

All API requests require a JWT token in the Authorization header:

Authorization: Bearer {jwt_token}

Obtain JWT Token

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

{
  "username": "operator",
  "password": "password123"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Refresh Token

POST /auth/refresh
Authorization: Bearer {jwt_token}

System Management

Health Check

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.0.0",
  "components": {
    "database": "healthy",
    "opcua_server": "healthy",
    "modbus_server": "healthy",
    "rest_api": "healthy"
  }
}

System Status

GET /status
Authorization: Bearer {jwt_token}

Response:

{
  "application": {
    "name": "Calejo Control Adapter",
    "version": "2.0.0",
    "environment": "production",
    "uptime": "5d 12h 30m"
  },
  "performance": {
    "cpu_usage": 45.2,
    "memory_usage": 67.8,
    "active_connections": 12,
    "response_time_avg": 85
  },
  "safety": {
    "emergency_stop_active": false,
    "failsafe_mode": false,
    "safety_violations": 0
  }
}

Pump Station Management

List Pump Stations

GET /pump-stations
Authorization: Bearer {jwt_token}

Response:

{
  "stations": [
    {
      "station_id": "station_001",
      "name": "Main Pump Station",
      "location": "Building A",
      "status": "operational",
      "pumps": [
        {
          "pump_id": "pump_001",
          "name": "Primary Pump",
          "status": "running",
          "setpoint": 35.5,
          "actual_speed": 34.8,
          "safety_status": "normal"
        }
      ]
    }
  ]
}

Get Pump Station Details

GET /pump-stations/{station_id}
Authorization: Bearer {jwt_token}

Response:

{
  "station_id": "station_001",
  "name": "Main Pump Station",
  "location": "Building A",
  "status": "operational",
  "configuration": {
    "max_pumps": 4,
    "power_capacity": 150.0,
    "flow_capacity": 500.0
  },
  "pumps": [
    {
      "pump_id": "pump_001",
      "name": "Primary Pump",
      "type": "centrifugal",
      "power_rating": 75.0,
      "status": "running",
      "setpoint": 35.5,
      "actual_speed": 34.8,
      "efficiency": 87.2,
      "safety_status": "normal",
      "last_maintenance": "2024-01-10T08:00:00Z"
    }
  ]
}

Setpoint Control

Get Current Setpoints

GET /pump-stations/{station_id}/setpoints
Authorization: Bearer {jwt_token}

Response:

{
  "station_id": "station_001",
  "setpoints": [
    {
      "pump_id": "pump_001",
      "setpoint": 35.5,
      "actual_speed": 34.8,
      "timestamp": "2024-01-15T10:30:00Z",
      "source": "optimization"
    }
  ]
}

Update Setpoint

PUT /pump-stations/{station_id}/pumps/{pump_id}/setpoint
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "setpoint": 40.0,
  "reason": "Manual adjustment for testing",
  "operator": "operator_001"
}

Response:

{
  "success": true,
  "message": "Setpoint updated successfully",
  "data": {
    "pump_id": "pump_001",
    "requested_setpoint": 40.0,
    "enforced_setpoint": 40.0,
    "safety_violations": [],
    "timestamp": "2024-01-15T10:31:00Z"
  }
}

Batch Setpoint Update

PUT /pump-stations/{station_id}/setpoints
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "setpoints": [
    {
      "pump_id": "pump_001",
      "setpoint": 38.0
    },
    {
      "pump_id": "pump_002", 
      "setpoint": 42.0
    }
  ],
  "reason": "Optimization plan execution",
  "operator": "system"
}

Safety Operations

Emergency Stop

POST /pump-stations/{station_id}/emergency-stop
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "reason": "Emergency maintenance required",
  "operator": "operator_001"
}

Response:

{
  "success": true,
  "message": "Emergency stop activated for station station_001",
  "data": {
    "station_id": "station_001",
    "active": true,
    "activated_at": "2024-01-15T10:32:00Z",
    "activated_by": "operator_001",
    "reason": "Emergency maintenance required"
  }
}

Clear Emergency Stop

DELETE /pump-stations/{station_id}/emergency-stop
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "reason": "Maintenance completed",
  "operator": "operator_001"
}

Get Emergency Stop Status

GET /pump-stations/{station_id}/emergency-stop-status
Authorization: Bearer {jwt_token}

Response:

{
  "station_id": "station_001",
  "active": false,
  "activated_at": null,
  "activated_by": null,
  "reason": null
}

Get Safety Limits

GET /pump-stations/{station_id}/pumps/{pump_id}/safety-limits
Authorization: Bearer {jwt_token}

Response:

{
  "station_id": "station_001",
  "pump_id": "pump_001",
  "limits": {
    "hard_min_speed_hz": 20.0,
    "hard_max_speed_hz": 50.0,
    "hard_min_level_m": 1.5,
    "hard_max_level_m": 8.0,
    "hard_max_power_kw": 80.0,
    "max_speed_change_hz_per_min": 30.0
  },
  "violations": []
}

Configuration Management

Get System Configuration

GET /configuration
Authorization: Bearer {jwt_token}

Response:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "calejo",
    "user": "control_reader",
    "pool_size": 10,
    "max_overflow": 20
  },
  "protocols": {
    "opcua": {
      "enabled": true,
      "endpoint": "opc.tcp://0.0.0.0:4840",
      "security_policy": "Basic256Sha256"
    },
    "modbus": {
      "enabled": true,
      "host": "0.0.0.0",
      "port": 502,
      "max_connections": 100
    },
    "rest_api": {
      "enabled": true,
      "host": "0.0.0.0",
      "port": 8080,
      "cors_origins": ["https://dashboard.calejo.com"]
    }
  },
  "safety": {
    "timeout_seconds": 1200,
    "emergency_stop_timeout": 300,
    "default_limits": {
      "min_speed_hz": 20.0,
      "max_speed_hz": 50.0,
      "max_speed_change": 30.0
    }
  },
  "security": {
    "jwt_secret": "********",
    "token_expire_minutes": 60,
    "audit_log_enabled": true
  }
}

Update Configuration

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

{
  "protocols": {
    "rest_api": {
      "port": 8081
    }
  }
}

Response:

{
  "success": true,
  "message": "Configuration updated successfully",
  "restart_required": true,
  "changes": [
    {
      "field": "protocols.rest_api.port",
      "old_value": 8080,
      "new_value": 8081
    }
  ]
}

Monitoring & Metrics

Get Performance Metrics

GET /metrics
Authorization: Bearer {jwt_token}

Response:

{
  "system": {
    "cpu_usage_percent": 45.2,
    "memory_usage_percent": 67.8,
    "disk_usage_percent": 23.4,
    "network_bytes_sent": 1024576,
    "network_bytes_received": 2048576
  },
  "application": {
    "active_connections": 12,
    "requests_per_minute": 45,
    "average_response_time_ms": 85,
    "error_rate_percent": 0.5
  },
  "database": {
    "active_connections": 8,
    "queries_per_second": 12.5,
    "cache_hit_ratio": 0.95
  },
  "protocols": {
    "opcua": {
      "active_sessions": 3,
      "nodes_published": 150,
      "messages_per_second": 25.3
    },
    "modbus": {
      "active_connections": 5,
      "requests_per_second": 10.2
    }
  }
}

Get Historical Metrics

GET /metrics/historical?metric=cpu_usage&hours=24
Authorization: Bearer {jwt_token}

Response:

{
  "metric": "cpu_usage",
  "time_range": {
    "start": "2024-01-14T10:30:00Z",
    "end": "2024-01-15T10:30:00Z"
  },
  "data": [
    {
      "timestamp": "2024-01-14T10:30:00Z",
      "value": 42.1
    },
    {
      "timestamp": "2024-01-14T11:30:00Z", 
      "value": 45.8
    }
  ]
}

Audit & Logging

Get Audit Logs

GET /audit-logs?start_time=2024-01-15T00:00:00Z&end_time=2024-01-15T23:59:59Z&event_type=SETPOINT_CHANGED
Authorization: Bearer {jwt_token}

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:31:00Z",
      "event_type": "SETPOINT_CHANGED",
      "severity": "HIGH",
      "user_id": "operator_001",
      "station_id": "station_001",
      "pump_id": "pump_001",
      "ip_address": "192.168.1.100",
      "protocol": "REST_API",
      "action": "setpoint_update",
      "resource": "pump_001.setpoint",
      "result": "success",
      "reason": "Manual adjustment for testing",
      "compliance_standard": ["IEC_62443", "ISO_27001", "NIS2"],
      "event_data": {
        "requested_setpoint": 40.0,
        "enforced_setpoint": 40.0
      }
    }
  ],
  "total_count": 1,
  "time_range": {
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-15T23:59:59Z"
  }
}

Get System Logs

GET /system-logs?level=ERROR&hours=24
Authorization: Bearer {jwt_token}

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-15T08:15:23Z",
      "level": "ERROR",
      "component": "safety",
      "message": "Safety limit violation detected for pump_001",
      "details": {
        "station_id": "station_001",
        "pump_id": "pump_001",
        "violation": "ABOVE_MAX_SPEED",
        "requested_setpoint": 52.0,
        "enforced_setpoint": 50.0
      }
    }
  ]
}

User Management

List Users

GET /users
Authorization: Bearer {jwt_token}

Response:

{
  "users": [
    {
      "user_id": "admin_001",
      "username": "admin",
      "email": "admin@calejo.com",
      "role": "administrator",
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "last_login": "2024-01-15T09:30:00Z"
    },
    {
      "user_id": "operator_001",
      "username": "operator",
      "email": "operator@calejo.com",
      "role": "operator",
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "last_login": "2024-01-15T08:45:00Z"
    }
  ]
}

Create User

POST /users
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "username": "new_operator",
  "email": "new_operator@calejo.com",
  "role": "operator",
  "password": "secure_password123"
}

Update User

PUT /users/{user_id}
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "email": "updated@calejo.com",
  "role": "supervisor"
}

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid setpoint value provided",
    "details": {
      "field": "setpoint",
      "value": 60.0,
      "constraint": "Must be between 20.0 and 50.0"
    },
    "timestamp": "2024-01-15T10:31:00Z",
    "request_id": "req_123456789"
  }
}

Common Error Codes

Code HTTP Status Description
AUTH_REQUIRED 401 Authentication required
INVALID_TOKEN 401 Invalid or expired token
PERMISSION_DENIED 403 Insufficient permissions
VALIDATION_ERROR 400 Invalid request parameters
SAFETY_VIOLATION 422 Request violates safety limits
EMERGENCY_STOP_ACTIVE 423 Emergency stop is active
RESOURCE_NOT_FOUND 404 Requested resource not found
INTERNAL_ERROR 500 Internal server error

Rate Limiting

Rate Limits

Endpoint Category Requests per Minute Burst Limit
Authentication 10 20
Read Operations 60 100
Write Operations 30 50
Safety Operations 5 10

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642242600

This API reference provides comprehensive documentation for all available endpoints. Always use HTTPS in production environments and follow security best practices for API key management.