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.
- 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) } } - 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 } } - 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 } - Get application list
GET: /rest-api/applications-list
{ "status": "success", "applicationList": ["live","test"], // List of all available applications "applicationListSize": 2 // Number of items } - 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 } } - 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 } - 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)" } } } - 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"}] } - Server shutdown
GET: /rest-api/shutdown-server
{ command: "shutdown", // Command name status: "success" // Action status } - Register group
POST: /rest-api/register-group
Post fields:
command registerStreamGroup groupName A name for a group Name. For more reference please check Gateway configuration section. data JSON source array. For more reference please check Gateway server section. { command: "registerStreamGroup", // Command name status: "success" // Action status } - Unregister group
POST: /rest-api/unregister-group
Post fields:
command unregisterStreamGroup groupName A name for a group Name. For more reference please check Gateway configuration section. { command: "unregisterStreamGroup", // Command name status: "success" // Action status }