How can I administer a Streaming application using REST calls?

Streaming Web Services

By default, each installed Streaming node's services host several "webservice" endpoints as shown by using command:

$ epadmin display services --servicetype=webservice

Service Name = admin-ui.A.chp
Service Type = webservice
Network Address = http://mysystem:8008/admin-ui

Service Name = admin.A.chp
Service Type = webservice
Network Address = http://mysystem:8008/admin

Service Name = healthcheck.A.chp
Service Type = webservice
Network Address = http://mysystem:8008/healthcheck

Service Name = metrics.A.chp
Service Type = webservice
Network Address = http://mysystem:8008/metrics

and

$ epadmin --adminport=22000 display web

Service Name = http.A.chp
Network Address = http://mysystem:8008
Web Help UI Address = http://mysystem:8008/helpui
Status = STARTED
Web Services = healthcheck,admin-ui,metrics,admin

The "adminport" shown is either assigned randomly from available open ports, or assigned by configuration and will likely be different in your environment. You may instead use the "servicename" parameter.

That the default port '8008' may be different in your environment if that port was already in use when the node was started. By default, if a port is in use already, then the node searches incrementally for another available port in the next nine port numbers. These may also be modified by configuration. No specific port number is guaranteed unless you have taken care to prevent other services from using it on the system running Streaming. If the system has multiple Streaming applications running on it, then the port number selected for each will be different.

The available web services are described in the documentation in section:

• TIBCO Streaming > StreamBase Admin Guide > StreamBase Runtime REST API
  
  

Webservices may be disabled on a node by using a NodeDeploy configuration when installing using the webEnable and webUIEnable settings.

Administrator REST Endpoint

The Admin Web Service requires a login to create a session cookie before additional administrative commands are allowed. By default this uses Basic Authentication (username, password) with credentials validated by the LocalAuthenticationRealm. Without custom configuration the username is the user-name of the account responsible for installing the node, with an empty password.

In the following examples, the curl utility is used to precisely identify the required parts of the communication to the REST API.

1. Initial login:

$ curl -X POST "[http://localhost:8008/admin/v1/login](http://localhost:8008/admin/v1/login)" -H "accept: **/**" -d "" -D - -c cookies.txt -u "username:userpassword"  

This obtains a session cookie and stores it for later use. This is automatically done by most REST frameworks, but check your programming language HTTP library support for custom client development.

If using an empty password, the syntax is '-u "username:"' to provide the Basic Auth credentials.

2. Running an 'epadmin' command:

To execute the 'epadmin display engine' command, the target is "engine" and the command is "display":

curl --cookie cookies.txt -X POST "http://localhost:8008/admin/v1/targets/engine?command=display" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "files=string"

The session cookie is retrieved from the cookies.txt file and the webservice needs to have been running continuously without interruption between obtaining the cookie and later use. Refresh the cookie by logging in again.

The command shows that the response payload is expected to be JSON formatted.

REST Command Help

Specific commands may be exercised in the browser by using the "helpui" endpoint (as shown above in the 'display web' command example). This provides form-based access to the "healthcheck", "metrics", and "admin" REST APIs and shows the equivalent curl command and Request and Response messages.

Steps to use:

1. install the Streaming node, e.g. epadmin install node --nodename=A.X --application=myapp.zip --adminport=22000
2. obtain the "Web Help UI Address" using command: epadmin --adminport=22000 display web
3. open a Web Browser page to that URL, e.g. http://mysystem:8008/helpui
4. select the "admin" Web Service
5. use the "Login" command target
6. from the same page, explore the available commands

Once you have identified the REST URL and parameters, use the same from your preferred client to support integration and automation.

See all topics in the "StreamBase Runtime REST API" documentation section (linked above) for additional background, limitations, and extensibility.

Provides examples of discovery, authentication, and use of a Streaming node's available web services, including execution of 'epadmin' commands using the REST API.

Product documentation:

• TIBCO Streaming > StreamBase Admin Guide > StreamBase Runtime REST API