REST API Integration ¶

RT Server provides a comprehensive REST API for programmatic control and monitoring. This enables integration with custom applications, monitoring systems, and automated deployment pipelines.

API Overview ¶

The REST API is organized into three main namespaces:

RT Core API - Instance management, input/output control, system operations
ONVIF API - Camera discovery and ONVIF device management
SecuRT API - Security analytics configuration and events

Enabling REST API ¶

The REST API is enabled by default when running RT Server, but can be configured:

Command Line Options ¶

# Windows
rtservice.exe --webserver-port 3546

# Linux Docker
./run.sh --daemon --api_port 3546

Configuration File ¶

Configure in rtconfig.json:

{
  "webserver": {
    "enabled": true,
    "port": 3546,
    "host": "0.0.0.0"
  }
}

Default Endpoints ¶

Base URL: http://server-ip:3546
API Documentation: http://server-ip:3546 (interactive docs)
Health Check: http://server-ip:3546/api/v1/health

Quick Start Examples ¶

Authentication ¶

Currently, the REST API does not require authentication. Ensure proper network security controls are in place.

Basic Instance Operations ¶

List All Instances ¶

curl -X GET "http://localhost:3546/api/v1/instances"

{
  "instances": [
    {
      "id": "security-camera-1",
      "status": "running",
      "solution": "securt",
      "uptime": 3600
    }
  ]
}

Start an Instance ¶

curl -X POST "http://localhost:3546/api/v1/instances/security-camera-1/start"

Stop an Instance ¶

curl -X POST "http://localhost:3546/api/v1/instances/security-camera-1/stop"

Get Instance Status ¶

curl -X GET "http://localhost:3546/api/v1/instances/security-camera-1/status"

System Information ¶

Server Health ¶

curl -X GET "http://localhost:3546/api/v1/health"

{
  "status": "healthy",
  "uptime": 86400,
  "version": "2024.1.0",
  "instances_running": 3,
  "cpu_usage": 45.2,
  "memory_usage": 67.8
}

Available Solutions ¶

curl -X GET "http://localhost:3546/api/v1/solutions"

Integration Patterns ¶

Monitoring Integration ¶

import requests
import time

def monitor_rt_server(base_url="http://localhost:3546"):
    """Monitor RT Server health and instances"""

    # Check server health
    health = requests.get(f"{base_url}/api/v1/health").json()
    if health["status"] != "healthy":
        print(f"Server unhealthy: {health}")
        return False

    # Check instance status
    instances = requests.get(f"{base_url}/api/v1/instances").json()
    for instance in instances["instances"]:
        if instance["status"] != "running":
            print(f"Instance {instance['id']} not running")
            # Attempt restart
            requests.post(f"{base_url}/api/v1/instances/{instance['id']}/start")

    return True

# Monitor every 30 seconds
while True:
    monitor_rt_server()
    time.sleep(30)

Automated Deployment ¶

#!/bin/bash
# Deploy new instance configuration

RTSERVER_URL="http://localhost:3546"
INSTANCE_ID="new-camera"

# Create new instance
curl -X POST "$RTSERVER_URL/api/v1/instances" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "'$INSTANCE_ID'",
    "solution": "securt",
    "input": {
      "type": "rtsp",
      "url": "rtsp://camera.example.com/stream"
    }
  }'

# Start the instance
curl -X POST "$RTSERVER_URL/api/v1/instances/$INSTANCE_ID/start"

# Verify it's running
curl -X GET "$RTSERVER_URL/api/v1/instances/$INSTANCE_ID/status"

Event Processing ¶

// JavaScript example for processing events
async function processEvents() {
    const response = await fetch('http://localhost:3546/api/v1/events');
    const events = await response.json();

    events.forEach(event => {
        switch(event.type) {
            case 'detection':
                handleDetectionEvent(event);
                break;
            case 'tripwire':
                handleTripwireEvent(event);
                break;
            case 'zone_enter':
                handleZoneEvent(event);
                break;
        }
    });
}

function handleDetectionEvent(event) {
    console.log(`Detection in ${event.instance}: ${event.class} (${event.confidence})`);
    // Send to external system, log to database, etc.
}

API Documentation ¶

Interactive Documentation ¶

Access interactive API documentation at: http://server-ip:3546

The interactive docs allow you to: - Browse all available endpoints - Test API calls directly from the browser - View request/response schemas - See example payloads

API Reference ¶

For detailed endpoint documentation, see:

RT Core API - Complete endpoint reference
ONVIF API - Camera management endpoints
SecuRT API - Security analytics endpoints

Security Considerations ¶

Network Security ¶

{
  "webserver": {
    "host": "127.0.0.1",  // Bind to localhost only
    "port": 3546,
    "cors_enabled": false  // Disable CORS in production
  }
}

Reverse Proxy Setup (nginx)¶

server {
    listen 443 ssl;
    server_name rt-server.example.com;

    # SSL configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Authentication
    auth_basic "RT Server API";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://localhost:3546;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Error Handling ¶

HTTP Status Codes ¶

200: Success
400: Bad Request (invalid parameters)
404: Resource not found (instance doesn't exist)
500: Internal server error
503: Service unavailable (server overloaded)

Error Response Format ¶

{
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance 'camera-1' does not exist",
    "details": {
      "instance_id": "camera-1",
      "available_instances": ["camera-2", "camera-3"]
    }
  }
}

Performance Considerations ¶

Rate Limiting ¶

Consider implementing client-side rate limiting for API calls to avoid overwhelming RT Server.

Batch Operations ¶

Use batch endpoints when available to reduce API overhead:

# Start multiple instances
curl -X POST "http://localhost:3546/api/v1/instances/batch/start" \
  -H "Content-Type: application/json" \
  -d '{"instance_ids": ["cam1", "cam2", "cam3"]}'

Asynchronous Operations ¶

Some operations may be asynchronous. Poll status endpoints to check completion:

# Start long-running operation
TASK_ID=$(curl -X POST "http://localhost:3546/api/v1/operations/deploy" | jq -r .task_id)

# Poll for completion
while true; do
    STATUS=$(curl -s "http://localhost:3546/api/v1/tasks/$TASK_ID" | jq -r .status)
    if [ "$STATUS" = "completed" ]; then
        break
    fi
    sleep 5
done

Testing API Endpoints ¶

Using Browser ¶

Navigate to http://server-ip:3546
Use interactive documentation to test endpoints
View request/response examples

CORS for Browser Testing

If testing from documentation pages, you may need to install a browser extension to disable CORS restrictions, or enable CORS in RT Server configuration.

Using curl ¶

# Test server connectivity
curl -v http://localhost:3546/api/v1/health

# Test with verbose output for debugging
curl -v -X POST "http://localhost:3546/api/v1/instances/test/start"

Using Postman ¶

Import API documentation from http://server-ip:3546/openapi.json
Create collections for common operations
Set up environment variables for server URL and ports

Next Steps ¶

Web Panel - Browser interface for manual administration
Running RT Server - Advanced deployment configurations
RT Core API Documentation - Complete API reference