RESTful API - Basics - Storm Streaming Server

Before starting with Storm’s RESTful API, please make sure that it’s enabled in our preference.xml file. The default configuration will look as follow:

                        
<REST enabled="true">
  <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 X-API-Key.

You can leave IPWhiteList empty if you wish, but X-API-Key is mandatory.

Creating a Simple GET Request

Here is an example on how to create a very simple request using PHP. Storm uses X-API-Key for authorization.

                        
<?php

// API key
$apiKey = 'your_api_key_here';

// URL Address for API
$apiUrl = 'http://localhost/rest/info';

// cURL session initialization
$curl = curl_init($apiUrl);

// Optional settings
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'x-api-key: ' . $apiKey
]);

// Executing request
$response = curl_exec($curl);

// Checking for request execution errors
if ($response === false) {
    $error = curl_error($curl);
    echo 'Request execution error: ' . $error;
} else {
    // Checking the response status
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    switch ($httpCode) {
        case 200:
            // Success - processing the response
            $responseData = json_decode($response, true);
            // Handle the response data...
            break;
        case 401:
            // Authentication failure
            echo 'Authentication failed. Access denied.';
            break;
        case 404:
            // Invalid URL
            echo 'Invalid URL. Resource not found.';
            break;
        case 500:
            // Server-side error
            echo 'Server-side error. Please try again later.';
            break;
        default:
            // Other response codes
            echo 'Unexpected response code: ' . $httpCode;
            break;
    }
}

// Closing the cURL session
curl_close($curl);
?>
                    

Creating POST & PUT Requests

In order to create a POST or PUT request we’ll have to specify Content-Type and add CURLOPT_CUSTOMREQUEST and POSTFIELDS fields like in this example.

Storm accepts POST data as JSON encoded strings.

                        
<?php

// API key
$apiKey = 'your_api_key_here';

// Data to send as JSON
$jsonData = json_encode($data);

// Initialize cURL session
$curl = curl_init($apiUrl);

// Set request options
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($jsonData),
'x-api-key: ' . $apiKey
));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData);

// Execute the PUT request
$response = curl_exec($curl);

// Optional: check for errors
if ($response === false) {
    echo 'Request error: ' . curl_error($curl);
} else {
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    echo 'HTTP Response Code: ' . $httpCode;
    // Optionally decode and handle response
    $responseData = json_decode($response, true);
    // Process $responseData as needed
}

// Close cURL session
curl_close($curl);
?>
                    

Answer Format

All responses are JSON-based objects. Each response contains status field, which indicated whenever operation was “success” or “failed”. Field “message” is provided whenever an error occurs.

                        
HTTP/1.1 200 OK
Content-Type: application/json

{
   "status":"success",
   "data":{
      "status":"running",
      "startDate":1685397038
   }
}
                    

or:

                        
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
   "status":"failed",
   "message":"Authorization failed",
}

                

Error Codes

Storm’s response codes follow standard HTTP schemes: