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);
Available API
Below you’ll find a list of available APIs for basic server management.
- Get Storms info
GET: /rest-api/info
Answer: 200 OK
{ "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
Answer: 200 OK
{ "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
Answer: 200 OK
{ "streams": 100, // Number of streams "viewers": 10000, // Number of viewers "uptime": 3600 // Number of seconds since player start } - Get application list
GET: /rest-api/application-list
Answer: 200 OK
{ "applicationList": ["live","test"], // List of all available applications "applicationListSize": 2 // Number of items } - Get application data
GET: /rest-api/application/$applicationName
Answer: 200 OK
{ "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 statistics
GET: /rest-api/application/$applicationName/stats/$pageNumber/$itemsPerPage
Answer: 200 OK
{ "applicationName":"live" // Name of the application "pageNumber": 1, // Number of current page (starts with 1) "pageCount": 1, // Total number of pages "itemsPerPage": 10, // Number of items per page "streamListSize": 1, // Total number of items "streamList": [ { "streamName": "test", // Name of the stream "startTime": "qwerty", // Start time for this stream in Unix-time "viewers": 5, // SecureStream timeout "inboundBandwidth": 2341, // Incoming source bandwidth in kb/s "outboundBandwidth": 30433, // Outgoing distribution bandwidth in kb/s }, ] } - Add new application
POST: /rest-api/application
Request JSON Body:
// Content-Type: application/json { "applicationName":"live" // Name of the 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 } } - Remove existing application
DELETE: /rest-api/application
Request JSON Body:
// Content-Type: application/json { "applicationName":"live" // Name of the application } - Get application stream list
GET: /rest-api/stream-list/$applicationName
Answer: 200 OK
{ "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
Answer: 200 OK
{ "streamName": "test", // stream name (published name) "applicationName": "live", // application name "startTime": 1626728976567, // when the stream 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 "outboundBandwidth": 30433, // Outgoing distribution 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)" } } } - Create new steam (pre-authorization)
POST: /rest-api/stream/$applicationName
Request JSON Body: (internal RTMP Server)
{ "streamName": "test", // stream name (published name) "applicationName": "live", // application name "maxViewers": 1, // max number of viewers (you can omit this parameter, by default there is no limit) "source": { "type": "RTMP_SERVER", // RTMP_SERVER for local streams and RTMP_client for external streams "allowedIP": "192.168.0.1", // Restricted RTMP IP (OBS client for example), this parameter can be omitted "authUser": "testUser" // Restricted Auth User (must be created prior) } }Request JSON Body: (external RTMP Server)
// Content-Type: application/json { "streamName": "test", // stream name (published name) "applicationName": "live", // application name "maxViewers": 1, // max number of viewers (you can omit this parameter, by default there is no limit) "source": { "type": "RTMP_CLIENT", // RTMP_SERVER for local streams and RTMP_client for external streams "port": "443", // Connection port (usually 1935 for rtmp and 443 for rtmps) "url": "rtmp://domain.com/app/streamName", // rtmp link "authLogin": "myLogin", // rtmp authorization login "authPass": "12345", // rtmp authorization password } } - Delete (stop) existing stream
DELETE: /rest-api/stream/$applicationName
Request JSON Body:
// Content-Type: application/json { "streamName":"test" // Name of the stream } - Get stream viewers list
GET: /rest-api/stream/$applicationName/$streamName/viewer-list
Answer: 200 OK
// Content-Type: application/json { "streamName": "test", // stream name (published name) "applicationName": "live", // application name "viewersListSize": 1, // current number of viewers "viewersList": [{"id:":1, "ip":"192.168.0.1"}] } - Get stream viewers statistics
GET: /rest-api/stream/$applicationName/$streamName/viewer-stats/$pageNumber/$itemsPerPage
Answer: 200 OK
// Content-Type: application/json { "streamName": "test", // stream name (published name) "applicationName": "live", // application name "pageNumber": 1, // Number of current page "pageCount": 1, // Total number of pages "itemsPerPage": 10, // Number of items per page "viewersListSize": 1, // current number of viewers "viewersList": [ { "viewerID": 1, // id of a viewer "ip": "192.168.0.1", // ip address "device": "Desktop", // Possible values: Desktop, Tablet, Mobile "browser": "Firefox 101.0.1", // Possible values: Firefox, Chrome, Unknown "startTime": 1626728976567, // when client has been attached (unix-time) "outboundBandwidth": 2341, // Outgoing transport bandwidth in kb/s } ] } - Get viewer data
GET: /rest-api/stream/$applicationName/$streamName/viewer/$viewerID
Answer: 200 OK
// Content-Type: application/json { "viewerID": 1, // id of a viewer "streamName": "test", // stream name (published name) "applicationName": "live", // application name "ip": "192.168.0.1", // ip address "userAgent": "Mozilla/5.0...", // user agent as provided by a browser "device": "Desktop", // Possible values: Desktop, Tablet, Mobile "browser": "Firefox 101.0.1", // Possible values: Firefox, Chrome, Unknown "startTime": 1626728976567, // when client has been attached (unix-time) "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) "sendVideoPackets": 218, // Number of video data packets received "sendAudioPackets": 341, // Number of audio data packets received "inboundBandwidth": 2341, // Incoming transport bandwidth in kb/s "outboundBandwidth": 2341, // Outgoing transport bandwidth in kb/s } - Detach viewer from stream
DELETE: /rest-api/stream-viewers/$applicationName/$streamName
Answer: 200 OK
Request JSON Body:
// Content-Type: application/json { "viewerID": 1 // id of a viewer } - Get stream auth user list (global)
GET: /rest-api/stream-auth-list
Request JSON Body:
// Content-Type: application/json { "status": "success", "viewersListSize": 3, // current number of authorized credentials "viewersList": ["admin","jon","littlefinger"] } - Add stream auth user (global)
POST: /rest-api/stream-auth
Request JSON Body:
// Content-Type: application/json { "username": "daenerys", // new username "password": "Dracarys123!", // password for that user } - Delete stream auth user (global)
DELETE: /rest-api/stream-auth
Request JSON Body:
// Content-Type: application/json { "username": "daenerys", // target user } - Get stream auth user list (local)
GET: /rest-api/stream-auth-list/$applicationName
Answer: 200 OK
// Content-Type: application/json { "status": "success", "applicationName": "live", "viewersListSize": 3, // current number of authorized credentials "viewersList": ["admin","jon","littlefinger"] } - Add stream auth user (local)
POST: /rest-api/stream-auth/$applicationName
Request JSON Body:
// Content-Type: application/json { "username": "daenerys", // new username "password": "Dracarys123!", // password for that user } - Delete stream auth user (local)
DELETE: /rest-api/stream-auth/$applicationName
Request JSON Body:
// Content-Type: application/json { "username": "daenerys", // target user } - Register group
POST: /rest-api/group/$applicationName
Request JSON Body:
// Content-Type: application/json { "groupName": "test_group", // new username "data": [ ['streamName' => "test_stream_1080p", 'application' => 'live', 'streamInfo' => ['label' => '1080p', 'width' => 1920, 'height' => 1080, 'fps' => 30, 'bitrate' => 2500]], ['streamName' => "test_stream_720p", 'application' => 'live', 'streamInfo' => ['label' => '720p', 'width' => 1280, 'height' => 720, 'fps' => 30, 'bitrate' => 5000]], ['streamName' => "test_stream_360p", 'application' => 'live', 'streamInfo' => ['label' => '360p', 'width' => 640, 'height' => 360, 'fps' => 30, 'bitrate' => 7000]], ]; }For more reference on data parameter structure please check Gateway server section.
- Delete group
DELETE: /rest-api/group/$applicationName
Request JSON Body:
// Content-Type: application/json { "groupName": "test_group", // target group } - Server shutdown
GET: /rest-api/shutdown-server
- Server restart
GET: /rest-api/restart-server
Handling errors
Storm uses classic HTTP response codes to indicate the success or failure of an request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missing, etc.). Codes in the 5xx range indicate an error with Storm's servers.
Error JSON Body:
// Content-Type: application/json
{
"message": "XXX parameter is missing", // a readable error message
"type": "invalid_request_error" // possible errors types: api_error, invalid_request_error, auth_error
}