Skip to main content

API Guide

Striim's programming interfaces include:

  • REST API endpoints to retrieve WActionStore definitions (GET /wactions/def), query WActionStores (GET /wactions/search), and retrieve system health statistics (GET /health)

  • the Striim Application Management REST API, which allows you to manage the lifecycle (deploy, start, stop, undeploy, drop, etc.) of existing Striim applications, create new applications from templates, and retrieve file lineage data

  • the Java event publishing API, which allows Java applications to write directly to Striim streams

Using the Striim Application Management REST API

This API allows you to create and manage (deploy, start, stop, undeploy, drop, etc.) Striim applications, execute TQL commands, retrieve monitoring and file lineage data, and more. See the interactive documentation at https://striim.stoplight.io/docs/striim-application-management..

Getting a REST API authentication token

An authentication token must be included in all REST API calls using the token parameter. You can get a token using any REST client. For sample code to get a token using Java, .NET, Python, Ruby, and other languages, see github.com/striim/rest-api-samples/tree/master/v2.

http://<IP address>:<port>/security/authenticate

For example:

curl -X POST -d'username=admin&password=******' http://localhost:9080/security/authenticate

will return a token in the format {"token":"01e41da3-9ddf-4f51-982d-685b3587069e"}.

For sample code to get a token using Java, .NET, Python, Ruby, and other languages, see github.com/striim/rest-api-samples/tree/master/v2.

By default, Striim Platform tokens change only when the Striim server is restarted. To change that, see Setting the REST API token timeout.

Retrieving a WActionStore definition using the REST API

To retrieve the data definition for a WActionStore (for example, so that the custom application can use it to populate a field selector), the URI syntax is:

http://<IPAddress>:<port>/wactions/def?name=<namespace>.<WActionStore name>&token=<token>

See Getting a REST API authentication token.

For example, using curl (which requires the & between the WActionStore name and token to be escaped), if PosApp is running on localhost with the default port, and the token is 01e86e5f-ef7f-aab1-919f-000ec6fd8764, curl -X GET http://localhost:9080/wactions/def?"name=Samples.MerchantActivity&token=01e86e5f-ef7f-aab1-919f-000ec6fd8764"; will return:

CONTEXT DEFINITION : 
TYPE Samples.MerchantActivityContext CREATED 2018-06-12 09:46:21
ATTRIBUTES (
  MerchantId java.lang.String KEY 
  StartTime org.joda.time.DateTime
  CompanyName java.lang.String
  Category java.lang.String
  Status java.lang.String
  Count java.lang.Integer
  HourlyAve java.lang.Integer
  UpperLimit java.lang.Double
  LowerLimit java.lang.Double
  Zip java.lang.String
  City java.lang.String
  State java.lang.String
  LatVal java.lang.Double
  LongVal java.lang.Double
)

EVENT LIST DEFINITION : 
TYPE Samples.MerchantTxRate CREATED 2018-06-12 09:46:21
ATTRIBUTES (
  merchantId java.lang.String KEY 
  zip java.lang.String
  startTime org.joda.time.DateTime
  count java.lang.Integer
  totalAmount java.lang.Double
  hourlyAve java.lang.Integer
  upperLimit java.lang.Double
  lowerLimit java.lang.Double
  category java.lang.String
  status java.lang.String
)

Querying a WActionStore using the REST API

You may query a WActionStore using either a SELECT statement or keys from the REST API. The URI syntax for SELECT statements is:

http://<IPAddress>:<port>/wactions/search?name=<namespace>.<WActionStore name>&query=<select statement>&token=<token>

See Getting a REST API authentication token.

The SELECT statement uses the same syntax as a CQ or a dashboard query. End the select statement with a semicolon.

The syntax for REST API keys is:

http://<IPAddress>:<port>/wactions/search?name=<namespace>.<WActionStore name>
[&fields=<field name> ,...]
[&filter=
  [startTime:<query start time>,]
  [endTime:<query end time>,]
  [key:<key field value >,]
  [sortBy:<field name>,]
  [sortDir:asc,]
  [limit:<maximum number of results>,]
  [singleWactions:True]
]
&token=<token>

Note

Key:value pairs in the URI are case-sensitive.

If &fields and &filter are omitted, the query will return the WAction key and context fields from all WActions in random order.

Include &fields to specify the names of the fields to return, separated by commas. Alternatively, use &fields=default-allEvents to return the WAction key, context fields, and all events, or &fields=eventList to return only the events.

Include &filter to filter and/or sort the results:

  • startTime: if specified (Unix time in milliseconds), only WActions with a timestamp of this value or later will be returned

  • endTime: if specified, only WActions with a timestamp of this value or earlier will be returned

  • key: if specified, only WActions with the specified key field value will be returned

  • <field name>:$IN$ <value>~...: if specified, only WActions with the specified value(s) will be returned, for example, State:$IN$ California~Missouri~Nevada

  • singleWactions:True: if specified, all WActions will be returned; omit to return only the most recent WAction for each key field value)

  • sortBy: if specified, results will be sorted by this field

  • sortDir:asc: use with sortBy to sort results in ascending order; omit to sort results in descending order

  • limit:<n>: if specified, only the first n results will be returned

The following operators may be used in URI values:

operator

URI string

example

>

$GT$

HourlyAve$GT$1000 returns WActions where the hourly average is greater than than 1000

<

$LT$

HourlyAve$GT$1000 returns WActions where the hourly average is less 1000

>=

$GTE$

HourlyAve$GT$1000 returns WActions where the hourly average is greater than or equal to 1000

<=

$LTE$

HourlyAve$GT$1000 returns WActions where the hourly average is less than or equal to 1000

!=

$NE$

HourlyAve$NE$0 returns WActions where the hourly average is not zero

WActions are returned in JSON format. For example, here is one WAction from PosApp:

 {
    "{\"id\":\"01e3baa6-06ea-6f0b-be8a-28cfe91e2b2b\",\"key\":\"JGudv50ThZhzaAz1s2EhbtIg8qHLXlnHfIg\"}": {
        "context-Category": "WARM", 
        "context-City": "Garfield", 
        "context-CompanyName": "RueLaLa.com", 
        "context-Count": 938, 
        "context-HourlyAve": 948, 
        "context-LatVal": 46.9946, 
        "context-LongVal": -117.1523, 
        "context-LowerLimit": 790.625, 
        "context-MerchantId": "JGudv50ThZhzaAz1s2EhbtIg8qHLXlnHfIg", 
        "context-StartTime": 1363146829000, 
        "context-State": "Washington", 
        "context-Status": "OK", 
        "context-UpperLimit": 1137.6, 
        "context-Zip": "99130", 
        "key": "JGudv50ThZhzaAz1s2EhbtIg8qHLXlnHfIg", 
        "timestamp": 1396470806180, 
        "totalEvents": 41
    }
}

  • The id portion of the second line is the universally unique identifier (UUID) for this WAction. The key portion is the value of the WActionStore's key field, in this case MerchantID.

  • Lines 3-16 are the WAction's context field names and values.

  • key is another copy of the value of the WActionStore's key field.

  • timestamp is the time when the WAction was created (not the timestamp for the event, which is the context-StartTime value).

  • totalEvents is the number of events associated with this WAction.

Some examples using curl (which requires the spaces and & in the select statement to be escaped):

  • Return all WActions in Samples.MerchantActivity:

    curl -X GET http://localhost:9080/wactions/search?\
"name=Samples.MerchantActivity&\
query=select%20*%20from%20Samples.MerchantActivity&\
token=01e930a6-53c8-2201-8729-8cae4cf129d6";

  • Return WActions from Samples.MerchantActivity where the State field value is California, Missouri, or Nevada:

    curl -X GET http://localhost:9080/wactions/search?\
"name=Samples.MerchantActivity&\
State:$IN$%20California~Missouri~Nevada&\
token=01e930a1-cc1e-cfb1-8729-8cae4cf129d6";

  • Return only the State field value from all WActions in Samples.MerchantActivity:

    curl -X GET http://localhost:9080/wactions/search?\
"name=Samples.MerchantActivity&fields=State&\
token=01e930a1-cc1e-cfb1-8729-8cae4cf129d6";

These examples will all work if you run Samples.PosApp and replace the token value with a current one.

Monitoring using the system health REST API

This REST API endpoint allows you to retrieve various statistics about a Striim cluster. The basic URI syntax is:

  http://<IP address>:<port>/health?token=<token>

See Getting a REST API authentication token.

For example:

  http://localhost:9080/health?token=01e56161-9e42-3811-8157-685b3587069e

If you pretty-print the return, it will look something like this:

{
    "healthRecords": [
        {
            "kafkaHealthMap": {},
            "waStoreHealthMap": {
                "Samples.UnusualActivity": {
                    "fqWAStoreName": "Samples.UnusualActivity",
                    "writeRate": 0,
                    "lastWriteTime": 1508429845353
                } ...
            },
            "cacheHealthMap": {
                "Samples.MLogZipLookup": {
                    "size": 87130,
                    "lastRefresh": 1508429842638,
                    "fqCacheName": "Samples.MLogZipLookup"
                } ...
            },
            "clusterSize": 1,
            "appHealthMap": {
                "ns3.ProxyCheck": {
                    "lastModifiedTime": 1508371187853,
                    "fqAppName": "ns3.ProxyCheck",
                    "status": "CREATED"
                } ...
            },
            "serverHealthMap": {
                "Global.S192_168_1_14": {
                    "memory": 3693349800,
                    "cpu": "10.6%",
                    "elasticsearchFree": "56GB",
                    "fqServerName": "Global.S192_168_1_14",
                    "diskFree": "/: 56GB"
                }
            },
            "sourceHealthMap": {
                "Samples.AccessLogSource": {
                    "eventRate": 0,
                    "lastEventTime": 1508429845353,
                    "fqSourceName": "Samples.AccessLogSource"
                } ...
            },
            "elasticSearch": true,
            "targetHealthMap": {
                "Samples.CompanyAlertSub": {
                    "eventRate": 0,
                    "fqTargetName": "Samples.CompanyAlertSub",
                    "lastWriteTime": 1508429850358
                } ...
            },
            "stateChangeList": [
                {
                    "currentStatus": "CREATED",
                    "type": "APPLICATION",
                    "fqName": "Samples.MultiLogApp",
                    "previousStatus": "UNKNOWN",
                    "timestamp": 1508429825651
                } ...
            ],
            "issuesList": [],
            "startTime": 1508429825345,
            "id": "01e7b4e8-f298-76e2-ade3-685b3587069e",
            "endTime": 1508429855366,
            "derbyAlive": true,
            "agentCount": 0
        }
    ],
    "next": "/healthRecords?size=1&from=1",
    "prev": "/healthRecords?size=1&from=0"
}

  • Times are in milliseconds.

  • In cacheHealthMap, size is the amount of memory used, in bytes.

  • In serverHealthMap, cpu is the percentage used by the Java virtual machine at the time the server health was recorded, and memory is the amount of free memory usable by the server, in bytes.

issuesList will contain any log entries of level ERROR.

You can use start and end switches to return records from a specific time range, for example, http://<IP address>:<port>/health/healthRecords?start=<start time in milliseconds>&end=<end time in millisections>&token=<token>.

You can use the id value from the summary to return a subset of the data using the following syntax:

http://<IP address>:<port>/health/<id>/{agents|apps|caches|clustersize|derby|es|issues|servers|sources|statechanges|targets|wastores}?token=<token>

For example, curl -X GET http://<IP address>:<port>/health/<id>/apps?token=<token> will return only the appHealthMap portion of the data.

Using the Java event publishing API

You may use the Java event publishing API to develop Java applications that write directly to Striim streams.

Contact Striim support to download the SDK. Then extract the .zip file and open EventPublishAPI/docs/index.html for more information.

When an application using the stream is created with the WITH ENCRYPTION option (see CREATE APPLICATION ... END APPLICATION), the API will automatically encrypt the stream.