StreamBase Runtime REST API

Contents

Overview
Authentication
Querying the Web Service
Restrictions
Using epadmin to Manage the Web Service and Web Server
Web Server and Web Service Configuration via HOCON

Overview

Each running node includes a web server that presents REST API interfaces that support basic node administration functionality as well as node health queries. These REST interfaces are intended to provide insight into each node as a whole, not to any EventFlow, LiveView, or Java engines hosted by each node.

These REST interfaces are self-documenting, as is standard for OpenAPI-based REST APIs. You can determine the URLs to query a running node with a command like the following:

epadmin servicename=nodename.cluster display web

The example command output below shows the available web services — healthcheck and admin. 

[nodename.cluster] Service Name = http.nodename.cluster
[nodename.cluster] Network Address = http://example:8008
[nodename.cluster] Web Help UI Address = http://example:8008/helpui
[nodename.cluster] Status = STARTED
[nodename.cluster] Web Services = admin,healthcheck

To view the REST API page for your node, copy the Network Address or Web Help UI Address field as shown above to a browser. Depending on your node's authentication configuration, you may be prompted to enter a user name and password.

When a web service starts, it publishes a REST endpoint. The REST API page presents the help UI for your node. At the top of the page, you can select one of the following supported web services from the drop-down list:

  • healthcheck — Provides a simple check for the current node status. The returned node status can be one of:

    • STARTED

    • STOPPED

  • admin — Provides access to all available epadmin commands. Use to query the following endpoints:

    • GET /targets — Use to get help information from all available epadmin command targets for your node.

    • GET /targets/{target} — Use to get command help information for your node.

    • POST /targets/{target} — Execute an administration command.

    • GET /files/{filename} — Download your results into a file.

Authentication

All access through a web service endpoint must be authenticated using HTTP basic access authentication. This requires the HTTP user agent, for example a web browser, to provide a username and password. The username and password is authenticated by the authentication realm associated with the web service. By default, web service authentication uses the node administration realm. Authentication can also be changed per web service using the WebServiceBinding configuration object (see below) in a node deploy configuration. Also, the execution of the REST API command depends on trusted host being enabled in the node administration realm (which it is by default).

Authentication consists of the following:

  1. A username and password are sent from the client user agent.

  2. The username and password are authenticated using the web service authentication realm.

  3. Upon successful authentication, the administration command is executed with the username replaced with the default node username and no password.

  4. The administration command is authenticated using the node administration authentication realm.

Querying the Web Service

Regardless of web service, querying the Get and Post endpoints follows a similar paradigm except where noted.

  • Click Get or Post to display the basic format of how the node will respond to queries.

  • Click Try it out, supply the requested inputs, then click Execute. Notice the node status in the Response body.

  • Optionally you can download the generated response as a file to your machine, in JSON format.

  • To view the web service's OpenAPI description in JSON format in another browser window, click the URL next to the web service title (near top left corner of the UI page).

Restrictions

Admin web service restrictions:

POST Endpoint: Command Response

Viewing responses for the following epadmin commands via server sent events (SSE) is not supported by the REST API UI. To view the responses in JSON format, copy the location value in the response header to an SSE-supported web browser.

  • stream history

  • browse service

  • dequeue stream

Viewing responses for epadmin enqueue stream command via WebSocket is not supported in the REST API UI. To view the responses in JSON format, copy the location value in the response header to a WebSocket-supported web browser. For example:

POST Endpoint: File Upload

A limitation currently prevents the uploading of generated files from the POST target command endpoint, when parameters are specified with the sent command.

Get Endpoint: File Download

To download a file that you generated using epadmin (such as epadmin create snapshot) you must specify node directory/system/webservice/ws-file-cache/ {username} as your path to generate the file. You can specify the file name in the download file target. Note: The username is the username of the user that is logged in to the browser.

Using epadmin to Manage the Web Service and Web Server

Starting, stopping and displaying the web service:

The node's web server is enabled by default. To disable the web server, run commands like the following:

epadmin servicename=nodename.cluster stop web

Run a command like the following to verify the web service stopped:

epadmin servicename=nodename.cluster display web

[nodename.cluster] Service Name =
[nodename.cluster] Network Address = http://example:0
[nodename.cluster] Web Help UI Address = http://example:0/helpui
[nodename.cluster] Status = STOPPED
[nodename.cluster] Web Services =

Run a command like the following to restart the web service:

epadmin servicename=nodename.cluster start web

Run a command like the following to verify the web service restarted:

epadmin servicename=nodename.cluster display web

[nodename.cluster] Service Name = http.nodename.cluster
[nodename.cluster] Network Address = http://example:8008
[nodename.cluster] Web Help UI Address = http://example:8008/helpui
[nodename.cluster] Status = STARTED
[nodename.cluster] Web Services = admin,healthcheck

Run a command like the following to display additional information about the available web services and web server, including web service status, authentication realm in use, the URL to query, and so on:

epadmin servicename=A.X display web type=webservice

[nodename.cluster] Web Service Name = admin
[nodename.cluster] Engine = System::administration
[nodename.cluster] Base URL = http://example:8008/admin/v1
[nodename.cluster] Authentication Realm = default-realm
[nodename.cluster] Documentation Endpoint = http://example:8008/apidoc/admin.json
[nodename.cluster] Status = STARTED
[nodename.cluster] Total Number of Successful Requests/Responses = 1

[nodename.cluster] Web Service Name = healthcheck
[nodename.cluster] Engine = System::administration
[nodename.cluster] Base URL = http://example:8008/healthcheck/v1
[nodename.cluster] Authentication Realm = default-realm
[nodename.cluster] Documentation Endpoint = http://example:8008/apidoc/healthcheck.json
[nodename.cluster] Status = STARTED
[nodename.cluster] Total Number of Successful Requests/Responses = 0

Web Server and Web Service Configuration via HOCON

While the node's web server is enabled by default, you are free to edit the node HOCON configuration file to customize it. See HOCON Properties Explained for additional details.

These are the available web server and web service properties for the com.tibco.ep.dtm.configuration.node configuration file:

administration

Communication settings for administration transport. This is optional. If unset, a set of default values apply. These defaults are set in the contain types.

webEnable

This optional property enables the administration web server by default. Setting to false disables all queries of the Runtime REST API, whether browser-based or not (for example, the web server cannot be enabled from command line property using epadmin start web).

For example:

webEnable = true
webPort

Administration web server port number. A value of 0 causes the node to auto-generate the port number starting from 8008. Optional. Default value is 0.

For example:

webPort = 0
webUIEnable

This optional property enables the administration web server endpoint help UI by default, indicating the web interface is enabled and browser-based REST API queries are possible. False means browser-based REST API queries are not enabled though other queries are still possible through other methods.

For example:

webUIEnable = true
webMaximumFileSizeMegabytes

Maximum file size in megabytes for downloaded files if webFileSizeHandling is set to LIMITED_FILE_SIZE. Value must be > 0. Optional. Default value is 5.

webFileSizeHandling

Controls the maximum size of downloaded files. FILE_UPLOAD_NOT_ALLOWED disables file downloads. LIMITED_FILE_SIZE restricts file size to the value specified in webMaximumFileSizeMegabytes. UNLIMITED_FILE_SIZE sets no limit on downloaded file size. Optional. Default value is LIMITED_FILE_SIZE.

webMaximumFileCacheTimeMinutes

Time in minutes to cache downloaded files if webFileCacheTimeHandling is set to TIMED_CACHE. Value must be > 0. Optional. Default value is 15.

webFileCacheTimeHandling

Controls the caching of downloaded files. CACHE_FOREVER stores the files forever; files are never deleted. DO_NOT_CACHE never stores downloaded files on the node; files are immediately deleted after use. TIMED_CACHE caches the files for the amount of time specified in webMaximumFileCacheTimeMinutes. Optional. Default value is TIMED_CACHE.

webServiceBindings

A binding between a web service name and authentication realm name. This provides a mechanism to override the default node administration authentication realm for a specific web service. Available web services are: {admin | healthcheck}. This object is optional and has no default value.

authenticationRealmName

Authentication realm name for the specified web service binding. Required.

For example:

webServiceBindings = {
  "admin" = {
     authenticationRealmName = "my-local-auth-realm"
     }
  "healthcheck" = {
     authenticationRealmName = "my-other-local-auth-realm"
     }
  }