REST API Configuration - Storm Streaming Server

Storm Streaming Server includes a built-in REST API that enables programmatic access to server management, monitoring, and configuration. The API uses key-based authentication and supports IP whitelisting and CORS policies for secure access control.

Sample Configuration

The REST API is configured within the <RestSettings> block of the config/preferences.xml file. To use the API, you also need at least one VHost with the HTTP protocol enabled — the same VHost used for the Control Panel can serve REST API requests as well.

config/preferences.xml - REST API configuration

xml

<RestSettings enabled="true">
    <XApiKey>your-secure-api-key-here</XApiKey>
    <IPWhiteList>127.0.0.1, 192.168.10.20</IPWhiteList>
    <CorsSettings enabled="true">
        <AllowedOrigins>https://example.com, https://admin.example.com</AllowedOrigins>
    </CorsSettings>
</RestSettings>

Security Warning

Please make sure to set a strong API key before deploying your server. The key must be at least 8 characters long.

General Settings

The <RestSettings> element accepts the following parameters:

Parameter	Description	Required
`enabled`	Enables or disables the REST API. Optional attribute, defaults to `true`.	Yes
`<XApiKey>`	API key used for authentication. Must be at least 8 characters long. Sent via the `X-Api-Key` header.	Yes
`<IPWhiteList>`	A comma-separated list of IP addresses allowed to access the API. If left empty, all IPs are permitted.	No

Production Tip

Leaving the IP whitelist empty is not recommended for production environments. Restrict access to known administrative IPs whenever possible.

Authentication

Every request to the REST API must include the X-Api-Key header with the value matching the configured <XApiKey>. Requests without a valid key will be rejected.

Example API request

bash

curl -X GET http://127.0.0.1:8080/api/v1/server/status \
     -H "X-Api-Key: your-secure-api-key-here"

CORS Settings

Cross-Origin Resource Sharing (CORS) configuration controls which external domains are allowed to make requests to the REST API from a browser context. This is configured within the <CorsSettings> block.

config/preferences.xml - CORS configuration

xml

<CorsSettings enabled="true">
    <AllowedOrigins>https://example.com, https://admin.example.com</AllowedOrigins>
</CorsSettings>

Parameter	Description	Default
`enabled`	Enables or disables CORS support. Optional attribute.	`true`
`<AllowedOrigins>`	A comma-separated list of allowed origins. Use `` to allow all origins. Each origin must start with `http://` or `https://` (except ``).	`*`

Note

Using * as the allowed origin is convenient during development, but for production environments you should explicitly list only the domains that need access to the API.

Environment Variables

All parameters support environment variables using the ${EV:VARIABLE_NAME} syntax. This is particularly useful for sensitive values like the API key, allowing you to keep credentials out of configuration files.

config/preferences.xml - Using environment variables

xml

<RestSettings enabled="true">
    <XApiKey>${EV:STORM_API_KEY}</XApiKey>
    <IPWhiteList>${EV:STORM_API_WHITELIST}</IPWhiteList>
    <CorsSettings enabled="true">
        <AllowedOrigins>${EV:STORM_CORS_ORIGINS}</AllowedOrigins>
    </CorsSettings>
</RestSettings>

Environment Variables

Fields locked by environment variables cannot be modified via the REST API itself.

Support Needed?

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