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 user list for basic auth. Each entry contains a username and a password.

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 doing this).

Creating a Simple GET Request

Here is an example on how to create a very simple request using PHP. Storm uses Basic Auth for authorization.

                        
<?php

// Authentication data for Basic Auth
$username = 'example_user';
$password = 'example_password';

// 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_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $username . ':' . $password);

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

                        
// 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_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $username . ':' . $password);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData);

// Execute the PUT request
$response = curl_exec($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: