Getting Started

This section explains how to send JSON-formatted messages to the ScaleOut service using REST APIs.

Configuration

Set Database Connection String

Modify the configuration file to set the database connection string used to connect to ScaleOut Active Caching databases. First, copy the “DatabaseConfiguration” section from your WebService.Api configuration file.

Windows: "C:\Program Files\ScaleOut_Software\StateServer\ActiveCachingWebUI\WebService.Api\appsettings.windows.json".
Linux: /usr/lib/soss-ac/soss-ac-web/appsettings.linux.json.

Next, modify the “DatabaseConfiguration” section in the messaging API configuration file to paste in the database configuration from your WebService.Api configuration file:

Windows: "C:\Program Files\ScaleOut_Software\StateServer\ActiveCachingWebUI\Messaging.Api\appsettings.windows.json".
Linux: /usr/lib/soss-ac/soss-ac-msg/appsettings.linux.json.

Enable the REST service

The REST Messaging service is installed by default on all ScaleOut StateServer hosts. It is not started by default, so run the following commands to start it:

net start soss-ac-msg

sudo systemctl start soss-ac-msg

The REST Messaging service will start listening on port 8801.

Note

if you enable the REST Messaging service on all hosts, you can use a load balancer to distribute incoming messages across all hosts.

Sending a Message

An HTTP client can be used to send messages to specific object instances so that they can be processed by a custom messaging module. For example, to send a temperature reading from a wind turbine to an instance identified as “turbine1” in a module called “windTurbine”, you could use curl from a bash shell as follows:

curl -X POST "https://localhost:8801/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF" -H "Content-Type: application/json" -d "[{ 'temp': 65, 'timestamp': $(date +%s) }]"

Python can be used to make the same request:

import requests
import time
requests.post('https://localhost:8801/api/v1/Messages/windTurbine/turbine1?apiKey=1234567890ABCDEF', json={"temp": "65", "timestamp": time.time()})

Important

The JSON messages you send to the REST API must match the message type(s) that you defined in your Java/C# message-processing project. If your message-handling code relies on special JSON features (like C#’s [JsonDerivedType] attribute), be sure that your JSON payload includes the supporting properties required by those features.