RESTful API - Basics - Storm Streaming Server

Before starting with Storm's RESTful API, please make sure that it's enabled in your preference.xml file.

Configuration

The default configuration will look as follows:

preference.xml

xml

<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:

IPWhiteList - can contain multiple IP addresses separated by a comma (space is optional)
X-API-Key - mandatory header for authentication

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.

GET Request Example

php

<?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.

PUT Request Example

php

<?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 a status field, which indicates whether the operation was "success" or "failed". The message field is provided whenever an error occurs.

Success response:

Success Response

json

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

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

Error response:

Error Response

json

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

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

Error Codes

Storm's response codes follow standard HTTP schemes:

Code	Description
200	OK - Request was successful
401	Authentication failure
404	Invalid URL - Resource not found
500	Server-side error

Support Needed?

If you have any questions or need assistance, please create a support ticket and our team will help you.