SecuRTRest Plugin¶
Description¶
SecuRTRest is a comprehensive REST API plugin designed specifically for the SecuRT security solution. It provides enterprise-grade HTTP-based API endpoints for security system integration, real-time analytics configuration, instance management, and seamless VMS integration through a fully documented OpenAPI 3.0 specification.
Key Features¶
- Complete REST API: 68+ endpoints covering all SecuRT functionality
- OpenAPI 3.0 Compliant: Auto-generated, fully documented API specification
- Real-Time Configuration: Dynamic analytics configuration without system restart
- VMS Integration Ready: Standardized REST interface for security management systems
- Comprehensive Analytics: 12+ area types and 3 line types for security analytics
- Instance Lifecycle Management: Full control over SecuRT instance creation, configuration, and monitoring
- Enterprise Security: Production-ready error handling and input validation
Use Cases¶
- VMS Integration: Integrate SecuRT with existing Video Management Systems
- Security Platform Integration: Connect with PSIM and security management platforms
- Custom Applications: Build custom security applications using the REST API
- Remote Configuration: Manage SecuRT instances remotely through HTTP API
- Analytics Management: Configure and monitor security analytics in real-time
- Multi-Instance Deployment: Manage multiple SecuRT instances from centralized systems
Requirements¶
Software Dependencies¶
Core Requirements: - CVEDIA-RT SecuRT solution - httplib HTTP server framework - nlohmann/json for JSON serialization - RTCORE (CVEDIA-RT core libraries)
Platform Support: - Primary: Windows (full support) - Secondary: Linux (compatible)
Network Requirements¶
Server Configuration:
- Default Port: 3546
- Protocol: HTTP/1.1
- Content-Type: application/json
- Base URL: http://localhost:3546/v1/securt/
Firewall Configuration:
# Allow inbound connections on SecuRTRest port
# Windows Firewall
netsh advfirewall firewall add rule name="SecuRTRest" dir=in action=allow protocol=TCP localport=3546
# Linux iptables
sudo iptables -A INPUT -p tcp --dport 3546 -j ACCEPT
REST API Overview¶
API Structure¶
The SecuRTRest plugin provides three main API categories:
1. Instance Management API - Instance lifecycle operations (create, update, delete) - Configuration management (motion areas, performance profiles) - Feature control (LPR, face detection, feature extraction) - Statistics and monitoring
2. Areas Management API - 12+ security analytics area types - Dynamic area configuration - Real-time area management
3. Lines Management API - 3 line-based analytics types - Crossing and counting line configuration - Directional analytics setup
Supported Analytics Types¶
Area-Based Analytics¶
| Area Type | Description | Key Parameters |
|---|---|---|
| Intrusion Detection | Detect unauthorized entry | Duration threshold, object classes |
| Crossing Areas | Monitor area crossing events | Entry/exit detection, dwell time |
| Loitering | Detect prolonged presence | Duration threshold, sensitivity |
| Crowding | Monitor crowd density | Person count thresholds, density |
| Occupancy | Track area occupancy | Max occupancy, duration |
| Dwelling | Detect stationary objects/people | Duration threshold, object classes |
| Crowd Estimation | Estimate crowd size | Density calculation, count estimation |
| Armed Person Detection | Detect weapons | Weapon classification, confidence |
| Object Left/Removed | Detect abandoned/removed objects | Duration, object persistence |
| Fallen Person | Detect fallen people | Pose analysis, duration threshold |
| ALPR | License plate recognition | OCR confidence, plate format |
| Vehicle Guard | Vehicle-specific detection | Vehicle classification, loitering |
| Face Covered | Detect masked faces | Face analysis, coverage detection |
Line-Based Analytics¶
| Line Type | Description | Key Parameters |
|---|---|---|
| Crossing Lines | Count objects crossing lines | Direction, object classes |
| Counting Lines | Bidirectional counting | In/out counting, object filtering |
| Tailgating | Detect tailgating behavior | Time threshold, person separation |
Configuration¶
Basic Server Configuration¶
{
"securtrest": {
"server": {
"host": "localhost",
"port": 3546,
"base_path": "/v1/securt",
"max_connections": 100,
"timeout_seconds": 30
},
"security": {
"enable_cors": true,
"allowed_origins": ["*"],
"enable_logging": true,
"log_requests": true
},
"performance": {
"thread_pool_size": 4,
"keep_alive": true,
"compression": true
}
}
}
Instance Configuration Schema¶
{
"instance_config": {
"name": "Security Camera 1",
"detector_mode": "SmartDetection",
"sensitivity": "Medium",
"sensor_modality": "RGB",
"metadata_mode": true,
"statistics_mode": true,
"debug_mode": false,
"diagnostics_mode": false,
"max_fps": 30,
"motion_area": {
"coordinates": [
{"x": 0.1, "y": 0.1},
{"x": 0.9, "y": 0.1},
{"x": 0.9, "y": 0.9},
{"x": 0.1, "y": 0.9}
]
},
"performance_profile": "Balanced"
}
}
Area Configuration Example¶
{
"intrusion_area": {
"id": "area_001",
"name": "Main Entrance",
"coordinates": [
{"x": 0.2, "y": 0.3},
{"x": 0.8, "y": 0.3},
{"x": 0.8, "y": 0.7},
{"x": 0.2, "y": 0.7}
],
"classes": ["Person", "Vehicle"],
"color": "#FF0000",
"duration_threshold": 5.0,
"sensitivity": "High"
}
}
Configuration Schema¶
| Parameter | Type | Default | Description |
|---|---|---|---|
server.host |
string | "localhost" | HTTP server bind address |
server.port |
integer | 3546 | HTTP server port |
server.base_path |
string | "/v1/securt" | API base path |
server.max_connections |
integer | 100 | Maximum concurrent connections |
server.timeout_seconds |
integer | 30 | Request timeout |
security.enable_cors |
boolean | true | Enable CORS headers |
security.allowed_origins |
array | ["*"] | Allowed CORS origins |
security.enable_logging |
boolean | true | Enable request logging |
performance.thread_pool_size |
integer | 4 | HTTP server thread pool size |
performance.keep_alive |
boolean | true | Enable HTTP keep-alive |
performance.compression |
boolean | true | Enable response compression |
API Reference¶
Core Data Models¶
Basic Types¶
// Coordinate system (normalized 0.0-1.0)
struct Coordinate {
double x; // Horizontal position (0.0 = left, 1.0 = right)
double y; // Vertical position (0.0 = top, 1.0 = bottom)
};
// Object classification
enum class ObjectClass {
Person,
Animal,
Vehicle,
Face,
Unknown
};
// Detection sensitivity
enum class Sensitivity {
Low,
Medium,
High
};
// Movement direction
enum class Direction {
Up,
Down,
Both
};
Instance Management¶
// Instance configuration
struct SecuRTInstanceWrite {
std::string name;
DetectorMode detectorMode;
Sensitivity sensitivity;
SensorModality sensorModality;
bool metadataMode;
bool statisticsMode;
bool debugMode;
bool diagnosticsMode;
std::optional<int> maxFps;
};
// Instance response
struct SecuRTInstanceRead {
std::string id;
std::string name;
DetectorMode detectorMode;
Sensitivity sensitivity;
// ... additional read-only fields
};
Area Management¶
// Base area structure
struct AreaBase {
std::string id;
std::string name;
std::vector<Coordinate> coordinates;
std::vector<ObjectClass> classes;
std::string color; // Hex color code
};
// Intrusion detection area
struct IntrusionAreaWrite : AreaBase {
double durationThreshold; // Seconds
Sensitivity sensitivity;
};
// Loitering area
struct LoiteringAreaWrite : AreaBase {
double durationThreshold; // Seconds
Sensitivity sensitivity;
};
// Crowding area
struct CrowdingAreaWrite : AreaBase {
int maxPersons;
double durationThreshold;
Sensitivity sensitivity;
};
Line Management¶
// Base line structure
struct LineBase {
std::string id;
std::string name;
std::vector<Coordinate> coordinates; // Line endpoints
std::vector<ObjectClass> classes;
std::string color;
Direction direction;
};
// Crossing line
struct CrossingLineWrite : LineBase {
// Inherits all base line properties
};
// Tailgating line
struct TailgatingLineWrite : LineBase {
double timeThreshold; // Seconds between crossings
};
REST API Endpoints¶
Instance Management¶
# Create new instance
POST /v1/securt/instance
Content-Type: application/json
{
"name": "Security Camera 1",
"detectorMode": "SmartDetection",
"sensitivity": "Medium",
"sensorModality": "RGB"
}
# Response: 201 Created
{
"id": "instance_12345",
"name": "Security Camera 1",
"detectorMode": "SmartDetection",
"sensitivity": "Medium",
"sensorModality": "RGB",
"createdAt": "2023-11-15T10:30:00Z"
}
# Update instance
PATCH /v1/securt/instance/{instanceId}
Content-Type: application/json
{
"name": "Updated Camera Name",
"sensitivity": "High"
}
# Response: 200 OK
{
"id": "instance_12345",
"name": "Updated Camera Name",
"sensitivity": "High"
}
# Get instance statistics
GET /v1/securt/instance/{instanceId}/stats
# Response: 200 OK
{
"instanceId": "instance_12345",
"uptime": 3600,
"framesProcessed": 108000,
"averageFps": 30.0,
"detectionCount": 1250,
"memoryUsage": "256MB",
"cpuUsage": 25.5
}
Area Management¶
# Create intrusion detection area
POST /v1/securt/instance/{instanceId}/area/intrusion
Content-Type: application/json
{
"name": "Main Entrance",
"coordinates": [
{"x": 0.2, "y": 0.3},
{"x": 0.8, "y": 0.3},
{"x": 0.8, "y": 0.7},
{"x": 0.2, "y": 0.7}
],
"classes": ["Person"],
"color": "#FF0000",
"durationThreshold": 3.0,
"sensitivity": "High"
}
# Response: 201 Created
{
"id": "area_001",
"name": "Main Entrance",
"type": "intrusion",
"coordinates": [...],
"classes": ["Person"],
"color": "#FF0000",
"durationThreshold": 3.0,
"sensitivity": "High",
"createdAt": "2023-11-15T10:35:00Z"
}
# Create loitering area
POST /v1/securt/instance/{instanceId}/area/loitering
Content-Type: application/json
{
"name": "Parking Lot",
"coordinates": [
{"x": 0.0, "y": 0.0},
{"x": 1.0, "y": 0.0},
{"x": 1.0, "y": 0.5},
{"x": 0.0, "y": 0.5}
],
"classes": ["Person", "Vehicle"],
"color": "#00FF00",
"durationThreshold": 30.0,
"sensitivity": "Medium"
}
# Get all areas for instance
GET /v1/securt/instance/{instanceId}/areas
# Response: 200 OK
{
"areas": [
{
"id": "area_001",
"type": "intrusion",
"name": "Main Entrance",
"coordinates": [...],
"active": true
},
{
"id": "area_002",
"type": "loitering",
"name": "Parking Lot",
"coordinates": [...],
"active": true
}
],
"totalCount": 2
}
Line Management¶
# Create crossing line
POST /v1/securt/instance/{instanceId}/line/crossing
Content-Type: application/json
{
"name": "Entry Gate",
"coordinates": [
{"x": 0.3, "y": 0.2},
{"x": 0.7, "y": 0.8}
],
"classes": ["Person", "Vehicle"],
"color": "#0000FF",
"direction": "Both"
}
# Response: 201 Created
{
"id": "line_001",
"type": "crossing",
"name": "Entry Gate",
"coordinates": [
{"x": 0.3, "y": 0.2},
{"x": 0.7, "y": 0.8}
],
"classes": ["Person", "Vehicle"],
"color": "#0000FF",
"direction": "Both",
"createdAt": "2023-11-15T10:40:00Z"
}
Error Handling¶
HTTP Status Codes¶
| Status Code | Description | Usage |
|---|---|---|
| 200 OK | Success | GET, PATCH operations |
| 201 Created | Resource created | POST operations |
| 400 Bad Request | Invalid request data | Validation errors |
| 404 Not Found | Resource not found | Invalid IDs |
| 409 Conflict | Resource already exists | Duplicate creation |
| 500 Internal Server Error | Server error | System failures |
Error Response Format¶
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid coordinate values",
"details": {
"field": "coordinates",
"value": "x coordinate must be between 0.0 and 1.0"
},
"timestamp": "2023-11-15T10:45:00Z"
}
}
Examples¶
Complete Instance Setup¶
#!/bin/bash
# Complete SecuRT instance configuration script
BASE_URL="http://localhost:3546/v1/securt"
INSTANCE_ID=""
# 1. Create instance
echo "Creating SecuRT instance..."
INSTANCE_RESPONSE=$(curl -s -X POST "$BASE_URL/instance" \
-H "Content-Type: application/json" \
-d '{
"name": "Main Security Camera",
"detectorMode": "SmartDetection",
"sensitivity": "Medium",
"sensorModality": "RGB",
"metadataMode": true,
"statisticsMode": true,
"maxFps": 30
}')
INSTANCE_ID=$(echo $INSTANCE_RESPONSE | jq -r '.id')
echo "Created instance: $INSTANCE_ID"
# 2. Configure motion detection area
echo "Setting up motion detection area..."
curl -s -X POST "$BASE_URL/instance/$INSTANCE_ID/motion_area" \
-H "Content-Type: application/json" \
-d '{
"coordinates": [
{"x": 0.1, "y": 0.1},
{"x": 0.9, "y": 0.1},
{"x": 0.9, "y": 0.9},
{"x": 0.1, "y": 0.9}
]
}'
# 3. Create intrusion detection area
echo "Creating intrusion detection area..."
curl -s -X POST "$BASE_URL/instance/$INSTANCE_ID/area/intrusion" \
-H "Content-Type: application/json" \
-d '{
"name": "Restricted Zone",
"coordinates": [
{"x": 0.3, "y": 0.3},
{"x": 0.7, "y": 0.3},
{"x": 0.7, "y": 0.6},
{"x": 0.3, "y": 0.6}
],
"classes": ["Person"],
"color": "#FF0000",
"durationThreshold": 2.0,
"sensitivity": "High"
}'
# 4. Create counting line
echo "Creating counting line..."
curl -s -X POST "$BASE_URL/instance/$INSTANCE_ID/line/crossing" \
-H "Content-Type: application/json" \
-d '{
"name": "Main Entrance",
"coordinates": [
{"x": 0.2, "y": 0.5},
{"x": 0.8, "y": 0.5}
],
"classes": ["Person"],
"color": "#00FF00",
"direction": "Both"
}'
# 5. Configure performance profile
echo "Setting performance profile..."
curl -s -X POST "$BASE_URL/instance/$INSTANCE_ID/performance_profile" \
-H "Content-Type: application/json" \
-d '{"profile": "Balanced"}'
# 6. Get instance statistics
echo "Getting instance statistics..."
curl -s "$BASE_URL/instance/$INSTANCE_ID/stats" | jq .
echo "SecuRT instance setup complete: $INSTANCE_ID"
Python Integration Example¶
import requests
import json
from typing import Dict, List, Optional
class SecuRTClient:
def __init__(self, base_url: str = "http://localhost:3546/v1/securt"):
self.base_url = base_url
self.session = requests.Session()
self.session.headers.update({
'Content-Type': 'application/json',
'User-Agent': 'SecuRT-Python-Client/1.0'
})
def create_instance(self, config: Dict) -> str:
"""Create new SecuRT instance"""
response = self.session.post(f"{self.base_url}/instance", json=config)
response.raise_for_status()
return response.json()['id']
def create_intrusion_area(self, instance_id: str, area_config: Dict) -> str:
"""Create intrusion detection area"""
url = f"{self.base_url}/instance/{instance_id}/area/intrusion"
response = self.session.post(url, json=area_config)
response.raise_for_status()
return response.json()['id']
def create_crossing_line(self, instance_id: str, line_config: Dict) -> str:
"""Create crossing line"""
url = f"{self.base_url}/instance/{instance_id}/line/crossing"
response = self.session.post(url, json=line_config)
response.raise_for_status()
return response.json()['id']
def get_instance_stats(self, instance_id: str) -> Dict:
"""Get instance statistics"""
response = self.session.get(f"{self.base_url}/instance/{instance_id}/stats")
response.raise_for_status()
return response.json()
def get_all_areas(self, instance_id: str) -> List[Dict]:
"""Get all configured areas"""
response = self.session.get(f"{self.base_url}/instance/{instance_id}/areas")
response.raise_for_status()
return response.json()['areas']
def delete_instance(self, instance_id: str) -> None:
"""Delete instance"""
response = self.session.delete(f"{self.base_url}/instance/{instance_id}")
response.raise_for_status()
# Usage example
if __name__ == "__main__":
client = SecuRTClient()
# Create instance
instance_config = {
"name": "Retail Store Camera",
"detectorMode": "SmartDetection",
"sensitivity": "Medium",
"sensorModality": "RGB",
"metadataMode": True,
"statisticsMode": True
}
instance_id = client.create_instance(instance_config)
print(f"Created instance: {instance_id}")
# Create areas
intrusion_area = {
"name": "Cash Register Area",
"coordinates": [
{"x": 0.4, "y": 0.3},
{"x": 0.8, "y": 0.3},
{"x": 0.8, "y": 0.7},
{"x": 0.4, "y": 0.7}
],
"classes": ["Person"],
"color": "#FF0000",
"durationThreshold": 3.0,
"sensitivity": "High"
}
area_id = client.create_intrusion_area(instance_id, intrusion_area)
print(f"Created intrusion area: {area_id}")
# Create counting line
counting_line = {
"name": "Store Entrance",
"coordinates": [
{"x": 0.1, "y": 0.5},
{"x": 0.9, "y": 0.5}
],
"classes": ["Person"],
"color": "#00FF00",
"direction": "Both"
}
line_id = client.create_crossing_line(instance_id, counting_line)
print(f"Created crossing line: {line_id}")
# Monitor statistics
stats = client.get_instance_stats(instance_id)
print(f"Instance stats: {json.dumps(stats, indent=2)}")
# List all configured areas
areas = client.get_all_areas(instance_id)
print(f"Configured areas: {len(areas)}")
for area in areas:
print(f" - {area['name']} ({area['type']})")
VMS Integration Example¶
// JavaScript/Node.js VMS integration
const axios = require('axios');
class SecuRTVMSIntegration {
constructor(baseUrl = 'http://localhost:3546/v1/securt') {
this.baseUrl = baseUrl;
this.client = axios.create({
baseURL: baseUrl,
timeout: 30000,
headers: {
'Content-Type': 'application/json'
}
});
}
async deploySecurityConfiguration(cameraId, config) {
try {
// 1. Create SecuRT instance for camera
const instanceResponse = await this.client.post('/instance', {
name: `Camera_${cameraId}`,
detectorMode: config.detectorMode || 'SmartDetection',
sensitivity: config.sensitivity || 'Medium',
sensorModality: config.sensorType || 'RGB',
metadataMode: true,
statisticsMode: true
});
const instanceId = instanceResponse.data.id;
console.log(`Created instance ${instanceId} for camera ${cameraId}`);
// 2. Configure motion detection
if (config.motionArea) {
await this.client.post(`/instance/${instanceId}/motion_area`, {
coordinates: config.motionArea.coordinates
});
}
// 3. Deploy security areas
const areaIds = [];
for (const areaConfig of config.securityAreas || []) {
const response = await this.client.post(
`/instance/${instanceId}/area/${areaConfig.type}`,
areaConfig
);
areaIds.push(response.data.id);
console.log(`Created ${areaConfig.type} area: ${response.data.id}`);
}
// 4. Deploy counting lines
const lineIds = [];
for (const lineConfig of config.countingLines || []) {
const response = await this.client.post(
`/instance/${instanceId}/line/${lineConfig.type}`,
lineConfig
);
lineIds.push(response.data.id);
console.log(`Created ${lineConfig.type} line: ${response.data.id}`);
}
// 5. Configure performance profile
if (config.performanceProfile) {
await this.client.post(`/instance/${instanceId}/performance_profile`, {
profile: config.performanceProfile
});
}
return {
instanceId,
areaIds,
lineIds,
status: 'deployed'
};
} catch (error) {
console.error(`Failed to deploy security configuration for camera ${cameraId}:`, error.message);
throw error;
}
}
async monitorInstance(instanceId) {
try {
const stats = await this.client.get(`/instance/${instanceId}/stats`);
const areas = await this.client.get(`/instance/${instanceId}/areas`);
const lines = await this.client.get(`/instance/${instanceId}/lines`);
return {
statistics: stats.data,
areas: areas.data.areas,
lines: lines.data.lines,
timestamp: new Date().toISOString()
};
} catch (error) {
console.error(`Failed to monitor instance ${instanceId}:`, error.message);
throw error;
}
}
async updateSecurityArea(instanceId, areaId, updates) {
try {
// Note: This would require a PATCH endpoint for area updates
// Currently, the API supports DELETE and recreate pattern
await this.client.delete(`/instance/${instanceId}/area/${areaId}`);
// Recreate with updates
const response = await this.client.post(
`/instance/${instanceId}/area/${updates.type}`,
updates
);
return response.data.id;
} catch (error) {
console.error(`Failed to update area ${areaId}:`, error.message);
throw error;
}
}
}
// Usage in VMS integration
const vmsIntegration = new SecuRTVMSIntegration();
// Deploy configuration for multiple cameras
const cameras = [
{
id: 'CAM001',
config: {
detectorMode: 'SmartDetection',
sensitivity: 'High',
sensorType: 'RGB',
motionArea: {
coordinates: [
{x: 0.0, y: 0.0},
{x: 1.0, y: 0.0},
{x: 1.0, y: 1.0},
{x: 0.0, y: 1.0}
]
},
securityAreas: [
{
type: 'intrusion',
name: 'Secure Area',
coordinates: [{x: 0.3, y: 0.3}, {x: 0.7, y: 0.3}, {x: 0.7, y: 0.7}, {x: 0.3, y: 0.7}],
classes: ['Person'],
color: '#FF0000',
durationThreshold: 2.0,
sensitivity: 'High'
}
],
countingLines: [
{
type: 'crossing',
name: 'Main Door',
coordinates: [{x: 0.2, y: 0.5}, {x: 0.8, y: 0.5}],
classes: ['Person'],
color: '#00FF00',
direction: 'Both'
}
],
performanceProfile: 'Balanced'
}
}
];
// Deploy configurations
Promise.all(cameras.map(camera =>
vmsIntegration.deploySecurityConfiguration(camera.id, camera.config)
)).then(results => {
console.log('All camera configurations deployed successfully');
// Start monitoring
results.forEach(result => {
setInterval(async () => {
try {
const monitor = await vmsIntegration.monitorInstance(result.instanceId);
console.log(`Instance ${result.instanceId} stats:`, monitor.statistics);
} catch (error) {
console.error('Monitoring error:', error.message);
}
}, 30000); // Monitor every 30 seconds
});
}).catch(error => {
console.error('Deployment failed:', error.message);
});
Performance Optimization¶
HTTP Server Tuning¶
// Custom HTTP server configuration
class OptimizedSecuRTServer {
public:
void configureServer() {
// Thread pool optimization
server_.set_thread_pool_count(std::thread::hardware_concurrency());
// Connection management
server_.set_keep_alive_max_count(100);
server_.set_keep_alive_timeout_sec(30);
// Request size limits
server_.set_payload_max_length(10 * 1024 * 1024); // 10MB
// Enable compression
server_.set_compress_threshold(1024);
// Timeout configuration
server_.set_read_timeout(30, 0); // 30 seconds
server_.set_write_timeout(30, 0); // 30 seconds
}
void enableRequestLogging() {
server_.set_logger([](const httplib::Request& req, const httplib::Response& res) {
PLOG_INFO << "[" << res.status << "] " << req.method << " " << req.path
<< " - " << res.body.length() << " bytes";
});
}
private:
httplib::Server server_;
};
Caching and Performance¶
// Response caching for frequently accessed data
class ResponseCache {
public:
void cacheResponse(const std::string& key, const std::string& response) {
std::lock_guard<std::mutex> lock(cache_mutex_);
CacheEntry entry;
entry.response = response;
entry.timestamp = std::chrono::steady_clock::now();
cache_[key] = entry;
// Cleanup old entries
if (cache_.size() > max_cache_size_) {
cleanupCache();
}
}
std::optional<std::string> getResponse(const std::string& key) {
std::lock_guard<std::mutex> lock(cache_mutex_);
auto it = cache_.find(key);
if (it != cache_.end()) {
auto age = std::chrono::steady_clock::now() - it->second.timestamp;
if (age < cache_ttl_) {
return it->second.response;
} else {
cache_.erase(it);
}
}
return std::nullopt;
}
private:
struct CacheEntry {
std::string response;
std::chrono::steady_clock::time_point timestamp;
};
std::unordered_map<std::string, CacheEntry> cache_;
std::mutex cache_mutex_;
size_t max_cache_size_ = 1000;
std::chrono::minutes cache_ttl_{5};
void cleanupCache() {
auto now = std::chrono::steady_clock::now();
auto it = cache_.begin();
while (it != cache_.end()) {
if (now - it->second.timestamp > cache_ttl_) {
it = cache_.erase(it);
} else {
++it;
}
}
}
};
Troubleshooting¶
Common Issues¶
Connection Refused
# Check if SecuRTRest is running
curl -f http://localhost:3546/v1/securt/health 2>/dev/null && echo "Server is running" || echo "Server is not responding"
# Check port availability
netstat -an | grep :3546
Invalid Coordinates
// Ensure coordinates are normalized (0.0-1.0)
{
"error": "Coordinates must be between 0.0 and 1.0",
"solution": "Convert pixel coordinates to normalized coordinates by dividing by image dimensions"
}
// Example conversion
// pixelX = 640, imageWidth = 1920 -> normalizedX = 640/1920 = 0.333
// pixelY = 360, imageHeight = 1080 -> normalizedY = 360/1080 = 0.333
Instance Not Found
# List all instances to verify IDs
curl http://localhost:3546/v1/securt/instances
# Check instance status
curl http://localhost:3546/v1/securt/instance/{instanceId}/stats
Error Recovery¶
# Python error handling example
class SecuRTErrorHandler:
def __init__(self, client):
self.client = client
self.max_retries = 3
self.retry_delay = 1.0
def robust_request(self, method, url, **kwargs):
for attempt in range(self.max_retries):
try:
response = getattr(self.client, method)(url, **kwargs)
response.raise_for_status()
return response
except requests.exceptions.ConnectionError:
if attempt < self.max_retries - 1:
print(f"Connection failed, retrying in {self.retry_delay}s...")
time.sleep(self.retry_delay)
self.retry_delay *= 2 # Exponential backoff
else:
raise
except requests.exceptions.HTTPError as e:
if e.response.status_code in [500, 502, 503, 504]:
# Server errors - retry
if attempt < self.max_retries - 1:
time.sleep(self.retry_delay)
continue
else:
# Client errors - don't retry
raise
raise Exception("Max retries exceeded")
Monitoring and Diagnostics¶
#!/bin/bash
# SecuRTRest health check script
BASE_URL="http://localhost:3546/v1/securt"
check_server_health() {
echo "Checking server connectivity..."
if curl -f -s "$BASE_URL/health" >/dev/null; then
echo "✓ Server is responding"
else
echo "✗ Server is not responding"
return 1
fi
}
check_instance_health() {
local instance_id=$1
echo "Checking instance health: $instance_id"
response=$(curl -s "$BASE_URL/instance/$instance_id/stats")
if [ $? -eq 0 ]; then
echo "✓ Instance is active"
echo "Stats: $(echo $response | jq -r '.framesProcessed // "N/A"') frames processed"
else
echo "✗ Instance is not responding"
return 1
fi
}
monitor_performance() {
local instance_id=$1
while true; do
stats=$(curl -s "$BASE_URL/instance/$instance_id/stats")
if [ $? -eq 0 ]; then
fps=$(echo $stats | jq -r '.averageFps // 0')
cpu=$(echo $stats | jq -r '.cpuUsage // 0')
memory=$(echo $stats | jq -r '.memoryUsage // "Unknown"')
echo "$(date): FPS=$fps, CPU=${cpu}%, Memory=$memory"
else
echo "$(date): Failed to get statistics"
fi
sleep 10
done
}
# Usage
check_server_health
if [ $? -eq 0 ]; then
# Add your instance ID here
INSTANCE_ID="instance_12345"
check_instance_health $INSTANCE_ID
# Uncomment to start monitoring
# monitor_performance $INSTANCE_ID
fi
Best Practices¶
API Integration Guidelines¶
- Error Handling: Implement comprehensive error handling with retry logic for server errors
- Rate Limiting: Respect server resources by implementing appropriate request intervals
- Validation: Validate coordinate ranges (0.0-1.0) before sending requests
- Monitoring: Implement health checks and performance monitoring
Security Considerations¶
- Network Security: Use HTTPS in production environments
- Access Control: Implement authentication and authorization
- Input Validation: Always validate input data before sending to API
- Logging: Monitor and log API access for security auditing
Performance Optimization¶
- Connection Pooling: Use HTTP connection pooling for multiple requests
- Caching: Cache frequently accessed configuration data
- Batch Operations: Group related operations when possible
- Resource Management: Clean up unused instances and areas
Integration Patterns¶
- VMS Integration: Use standardized REST API for VMS system integration
- Event Handling: Implement proper event handling and callbacks
- Configuration Management: Centralize security configuration management
- Monitoring: Implement comprehensive monitoring and alerting