Rest API - Storm Streaming Server

The Rest API makes it possible to retrieve basic information from the server and also to call some functions. Before we can access the API, it must be configured properly via the preferences.xml file

                        
<REST>
    <IPWhiteList>192.168.0.1, 192.168.0.2</IPWhiteList>
    <Authorization>
        <auth username="admin" password="admin" />
    </Authorization>
</REST>
                        

There are two levels of authorization for REST-API. The first is IPWhiteList, which can contain multiple IP addresses separated by a comma (space is optional). The second one is the user list for basic auth. You can leave either IPWhiteList or Authorization empty if you wish. If both lists are empty, no authorization is required at all (we do not advise on doing this).

Creating requests

Here is an example on how to create a very simple request using PHP. We're using Basic Auth for authorization here.

                        
$ch = curl_init("https://sub1.mydomain.com/rest-api/info");
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml', $additionalHeaders));
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "admin" . ":" . "admin");
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($ch);
curl_close($ch);
                        

API available

Below you’ll find a list of available APIs for basic server management.

  1. Get Storms info

    GET: /rest-api/info

                                        
    {
        "status": "success",
        "version": "1.0.3",                   // server version
        "branch": "main"                      // server branch (usually main or development)
        "os": {
            "name": "Mac OS X",               // OS name
            "version": "10.16"                // OS version
        },
        "jvm": {
            "vendor": "Oracle Corporation",   // Vendor for JVM
            "version": "13.0.1"               // Java version
        },
        "hardware": {
            "arch": "x86_64",                 // CPU architecture
            "cpuCount": 16                    // Number of processor units (including HT cores)
        }
    }
                                    
  2. Get server load

    GET: /rest-api/server-load

                                        
    {
        "status": "success",
        "cpu": {
            "currLoad": 0.10,               // Current CPU usage in %
            "avgLoad": 1.20,                // Average CPU usage in % (last minute)
        },
        "memory": {
            "total": 65536,                 // Total system memory
            "used": 30128,                  // Used system memory (total)
            "free": 35407                   // Free system memory (total)
            "commited": 24658                   // Memory assigned to server process
        }
    }
                                    
  3. Get general statistics

    GET: /rest-api/server-stats

                                        
    {
        "status": "success",
        "streams": 100,         // Number of streams
        "viewers": 10000,       // Number of viewers
        "uptime": 3600          // Number of seconds since player start
    }
                                    
  4. Get application list

    GET: /rest-api/applications-list

                                        
    {
        "status": "success",
        "applicationList": ["live","test"],    // List of all available applications
        "applicationListSize": 2               // Number of items
    }
                                    
  5. Get application statistics

    GET: /rest-api/application/$applicationName

                                        
    {
        "status": "success",
        "applicationName":"live"       // Name of the application
        "streamCount": 100,            // Number of streams under this application
        "viewerCount": 10000,          // Number of viewers in streams of that application
        "secureStream": {
            "isEnabled": true,         // Whenever secureStream option is enabled
            "password": "qwerty",      // Password for secureStream
            "timeout": 5,              // SecureStream timeout
        },
        "dvr": {
            "isEnabled": false,          // Whenever DVR option is enabled
            "cacheSize": 45,            // Cache duration in seconds
        }
    }
                                    
  6. Get application stream list

    GET: /rest-api/streams-list/$applicationName

                                        
    {
        "status": "success",
        "applicationName": "live",                // Name of requested application
        "streamsList": ["test_lq","test_hd"],     // List of active broadcasts
        "streamsListSize": 2                      // Number of items
    }
                                    
  7. Get stream data

    GET: /rest-api/stream/$applicationName/$streamName

                                        
    {
        "status": "success",
        "streamName": "test",             // stream name (published name)
        "applicationName": "live",        // application name
        "startTime": 1626728976567,       // when server was started(unix-time)
        "viewers": 1,                     // current number of viewers
        "source": {
            "type": "RTMP_SERVER",              // RTMP_SERVER for local streams and RTMP_client for external streams
            "state": "STREAMING",               // current state of the source e.g.: INITIATED, CONNECTED, STREAMING, CLOSED, NOT_FOUND, STARTED
            "transportThreadStatus": "OK!",     // This should always display "OK!"
            "firstPacketTime": 1626728972080,   // Time when first data packet arrived (unix-time)
            "lastPacketDeltaTime": 7244,        // Time of the last packet (combine with first packet time to get the actual time)
            "receivedVideoPackets": 218,        // Number of video data packets received
            "receivedAudioPackets": 341,        // Number of audio data packets received
            "inboundBandwidth": 2341,           // Incoming source bandwidth in kb/s
            "metadata": {
                "width": 1920,              // Video width
                "height": 1080,             // Video height
                "fps": 30,                  // Current FPS (Frames-per-seconds) count
                "isVFR": false,             // Whenever stream uses Variable Frame-Rate
                "videoCodec": "H264",       // Video codec
                "audioCodec": "AAC",        // Audio codec
                "audioSampleRate": 48000,   // Sample Rate for Audio
                "audioSampleSize": 0,       // Sample Size for Audio
                "encoder": "obs-output module (libobs version 26.0.2)"
            }
        }
    }
                                    
  8. Get stream viewers list

    GET: /rest-api/stream-viewers-list/$applicationName/$streamName

                                        
    {
        "status": "success",
        "streamName": "test",                       // stream name (published name)
        "applicationName": "live",                  // application name
        "viewersListSize": 1,                       // current number of viewers
        "viewersList": [{"id:":1, "ip":"192.168.0.1"}]
    }
                                    
  9. Server shutdown

    GET: /rest-api/shutdown-server

                                        
    {
        command: "shutdown",     // Command name
        status: "success"       // Action status
    }
    
                                    
  10. Register group

    POST: /rest-api/register-group

    Post fields:

    commandregisterStreamGroup
    groupNameA name for a group Name. For more reference please check Gateway configuration section.
    dataJSON source array. For more reference please check Gateway server section.
                                        
    {
        command: "registerStreamGroup",     // Command name
        status: "success"       // Action status
    }
    
                                    
  11. Unregister group

    POST: /rest-api/unregister-group

    Post fields:

    commandunregisterStreamGroup
    groupNameA name for a group Name. For more reference please check Gateway configuration section.
                                        
    {
        command: "unregisterStreamGroup",     // Command name
        status: "success"       // Action status
    }