API Documentation

REST API Overview

The RACE Management Console provides a comprehensive REST API for programmatic access to all system functionality. All endpoints return JSON responses and use standard HTTP status codes.

Base Configuration

Base URL

https://your-domain.com/api

Content Type

Content-Type: application/json

Response Format

All responses are JSON formatted with consistent structure

Authentication

Session-Based

Current implementation uses session-based authentication through the web interface.

Future Enhancements

API Key authentication
JWT token-based access
OAuth2 integration

API Endpoints

Template Management

GET /api/templates

Get All Templates

Retrieve all rule templates with optional filtering

POST /api/templates

Create Template

Create a new rule template with placeholders

PUT /api/templates/{id}

Update Template

Update existing template (if not deployed)

DELETE /api/templates/{id}

Delete Template

Remove template (if no deployed instances)

Instance Management

GET /api/instances

Get All Instances

Retrieve all template instances with status

POST /api/instances

Create Instance

Create new template instance with mappings

POST /api/instances/{id}/deploy

Deploy Instance

Activate instance for runtime execution

POST /api/instances/{id}/undeploy

Undeploy Instance

Deactivate instance and close active events

Event Management

GET /api/rule-events

Get Events

Retrieve events with filtering and pagination

PUT /api/rule-events/{id}

Update Event

Modify event details or close event

POST /api/rule-events/{id}/close

Close Event

Manually close an active event

DELETE /api/rule-events/{id}

Delete Event

Remove event from system (with audit trail)

Monitoring & System

GET /api/streams/active

Active Streams

Get all actively monitored data streams

GET /api/system-tags

System Tags

Get available system tags and current values

GET /api/packages

Get Packages

Retrieve all template packages

GET /api/plant-model

Plant Model

Get ISA-95 plant hierarchy structure

Request/Response Examples

Creating a Template

Request:

POST /api/templates
Content-Type: application/json

{
  "name": "Equipment Health Monitor",
  "description": "Monitor equipment operational status",
  "category": "maintenance",
  "package_id": 1,
  "color": "#28a745",
  "rules": [
    {
      "rule_id": "Equipment.HighTemp",
      "rule_name": "High Temperature Alert",
      "conditions": [
        {
          "stream": "<TEMP_SENSOR>",
          "operator": "greater_than",
          "value": 85.0
        }
      ],
      "event_name": "<EQUIPMENT>.HighTemp",
      "event_description": "Equipment temperature exceeded threshold"
    }
  ],
  "placeholders": [
    {
      "placeholder_name": "TEMP_SENSOR",
      "data_type": "NUM",
      "description": "Temperature sensor stream",
      "is_required": true
    },
    {
      "placeholder_name": "EQUIPMENT",
      "data_type": "STR",
      "description": "Equipment identifier",
      "is_required": true
    }
  ]
}

Response:

{
  "success": true,
  "message": "Template created successfully",
  "template": {
    "id": 15,
    "template_id": "TMPL_EQ_HEALTH_015",
    "name": "Equipment Health Monitor",
    "description": "Monitor equipment operational status",
    "category": "maintenance",
    "package_id": 1,
    "color": "#28a745",
    "is_active": true,
    "allow_instances": true,
    "created_at": "2025-08-07T07:45:00.000Z",
    "created_by": "User",
    "rules_count": 1,
    "placeholders_count": 2,
    "instances_count": 0
  }
}

Deploying an Instance

Request:

POST /api/instances/5/deploy

Response:

{
  "success": true,
  "message": "Instance deployed successfully",
  "instance": {
    "id": 5,
    "instance_id": "ROA022_INST",
    "instance_name": "Roaster 022 Health Monitor",
    "is_deployed": true,
    "deployment_date": "2025-08-07T07:45:15.000Z",
    "template": {
      "id": 15,
      "name": "Equipment Health Monitor"
    },
    "placeholder_mappings": {
      "TEMP_SENSOR": "Wonderbrew.Roaster022.Temperature.PV",
      "EQUIPMENT": "Roaster022"
    }
  }
}

Error Response

Error Response Format:

{
  "success": false,
  "error": "Template cannot be modified - has deployed instances",
  "details": {
    "template_id": 15,
    "deployed_instances": 3,
    "error_code": "TEMPLATE_IN_USE"
  }
}

HTTP Status Codes:

200 - Success
201 - Created
400 - Bad Request
403 - Forbidden (deployment protection)
404 - Not Found
500 - Internal Server Error

Query Parameters & Filtering

Event Filtering

Available query parameters for /api/rule-events:

hours - Filter events by time range (default: 24)
category - Filter by event category
is_active - Filter active/closed events
template_id - Filter by template
instance_id - Filter by instance
severity - Filter by severity level

Example:

GET /api/rule-events?hours=1&category=production&is_active=true

Template/Instance Filtering

Available query parameters:

package_id - Filter by package
category - Filter by category
is_active - Filter active items
is_deployed - Filter deployed instances
has_instances - Templates with instances

Pagination:

page - Page number (default: 1)
per_page - Items per page (default: 50)