CalejoControl/docs/API_REFERENCE.md

# 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:

```http
Authorization: Bearer {jwt_token}
```

### Obtain JWT Token

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

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

**Response**:
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### Refresh Token

```http
POST /auth/refresh
Authorization: Bearer {jwt_token}
```

## System Management

### Health Check

```http
GET /health
```

**Response**:
```json
{
  "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

```http
GET /status
Authorization: Bearer {jwt_token}
```

**Response**:
```json
{
  "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

```http
GET /pump-stations
Authorization: Bearer {jwt_token}
```

**Response**:
```json
{
  "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

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

**Response**:
```json
{
  "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

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

**Response**:
```json
{
  "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

```http
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**:
```json
{
  "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

```http
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

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

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

**Response**:
```json
{
  "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

```http
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

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

**Response**:
```json
{
  "station_id": "station_001",
  "active": false,
  "activated_at": null,
  "activated_by": null,
  "reason": null
}
```

### Get Safety Limits

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

**Response**:
```json
{
  "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

```http
GET /configuration
Authorization: Bearer {jwt_token}
```

**Response**:
```json
{
  "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

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

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

**Response**:
```json
{
  "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

```http
GET /metrics
Authorization: Bearer {jwt_token}
```

**Response**:
```json
{
  "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

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

**Response**:
```json
{
  "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

```http
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**:
```json
{
  "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

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

**Response**:
```json
{
  "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

```http
GET /users
Authorization: Bearer {jwt_token}
```

**Response**:
```json
{
  "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

```http
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

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

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

## Error Handling

### Error Response Format

```json
{
  "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

```http
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.*