Web

This article describes how to manage the web server and web services running in a node.

Introduction

The web server that hosts web services on a node is installed on a node as part of application installation. See Application Installation for details.

In addition to this article, the StreamBase Runtime REST API section of the StreamBase Administration Guide discusses the web services.

Administration

Administration is provided for both the web server and any web services running on a node. Details on current state can be displayed, along with starting and stopping them.

Web Server

The status of the web server is displayed using this command: 

epadmin --servicename A.X display web

This information is displayed for the web server:

  • Service Name — service name.

  • Network Address — URL to access web server.

  • Web Help UI Address — URL to access a help UI for all REST APIs exposed by installed web services.

  • Status — current status.

  • Web Services — list of all hosted web services running on the node.

The web server can be started or stopped using these commands: 

//
//  Start the web server
//
epadmin --servicename A.X start web

//
//  Stop the web server
//
epadmin --servicename A.X stop web

Web Services

The status of the web services running on a node is displayed using this command: 

epadmin --servicename A.X display web --type webservice

This information is displayed for a web service:

  • Web Service Name — web service name.

  • Engine — engine hosting web service.

  • Base URL — base URL to REST endpoint exposed by web service.

  • Authentication Realm — authentication realm being used.

  • Documentation Endpoint — URL to REST endpoint documentation.

  • Status — current status.

These additional details are displayed when the detailed parameter is specified: 

epadmin --servicename A.X display web --type webservice --detailed

  • Number of Requests with 1xx Response Status — total number of requests that received a 1xx informational response.

  • Number of Requests with 2xx Response Status — total number of requests that received a 2xx success response.

  • Number of Requests with 3xx Response Status — total number of requests that received a 3xx redirection response.

  • Number of Requests with 4xx Response Status — total number of requests that received a 4xx client error response.

  • Number of Requests with 5xx Response Status — total number of requests that received a 5xx server error response.

A web service can be started or stopped using these commands: 

//
//  Start all web services installed on the node
//
epadmin --servicename A.X start web --type webservice

//
//  Stop all web services running on the node
//
epadmin --servicename A.X stop web --type webservice

Help UI

When the web server is started a help UI is available. The URL for the help user interface is found in the Web Help UI Address field returned by the display web command as described in Web Server. The help UI supports:

  • selecting any web service endpoint.

  • display a full description of the REST API.

  • executing any request on the availability endpoints.

  • provide credentials as required to execute requests.

REST API Documentation

When a web service starts, it publishes a REST endpoint. The documentation for that endpoint is available at the URL found in the Documentation Endpoint field returned by the display web --type webservice command as described in Web Services. This endpoint returns OpenAPI specification of the REST API, as shown in the example below. Also see Open API Specifications for Web Services in the StreamBase References. 

curl --silent --user admin http://kapoho.local:8008/apidoc/healthcheck.json | json_pp
Enter host password for user 'admin':
{
   "securityDefinitions" : {
      "basicAuth" : {
         "in" : "header",
         "type" : "basicAuth",
         "name" : "basic_auth"
      }
   },
   "paths" : {
      "/status" : {
         "get" : {
            "tags" : [
               "Get the node status"
            ],
            "responses" : {
               "503" : {
                  "content" : {
                     "application/json" : {
                        "schema" : {
                           "$ref" : "#/components/schemas/NodeStatus"
                        },
                        "example" : {
                           "nodeName" : "nodeA",
                           "nodeState" : "STOPPED"
                        }
                     }
                  },
                  "description" : "Node is stopped or not discovered"
               },
               "200" : {
                  "description" : "Node is running",
                  "content" : {
                     "application/json" : {
                        "example" : {
                           "nodeName" : "nodeA",
                           "nodeState" : "STARTED"
                        },
                        "schema" : {
                           "$ref" : "#/components/schemas/NodeStatus"
                        }
                     }
                  }
               }
            },
            "summary" : "Check the current status of the node"
         }
      }
   },
   "servers" : [
      {
         "url" : "/healthcheck/v1/"
      }
   ],
   "components" : {
      "schemas" : {
         "NodeStatus" : {
            "type" : "object",
            "properties" : {
               "nodeName" : {
                  "type" : "string"
               },
               "nodeState" : {
                  "type" : "string",
                  "description" : "Node state",
                  "enum" : [
                     "STARTED",
                     "STOPPED",
                     "NOT_DISCOVERED"
                  ]
               }
            }
         }
      }
   },
   "info" : {
      "version" : "1.0.0",
      "description" : "<b>OpenAPI specification of the Health Check REST API</b>",
      "title" : "Health Check REST API"
   },
   "openapi" : "3.0.1"
}

Supported Web Services

These web services are always available on a node if the web server is enabled:

  • admin — full access to all epadmin administration commands.

  • healthcheck — simple are you alive? check for a node.

  • metrics — access to all register metrics.

Each of these web services is described in more detail in the sections below.

See Open API Specifications for Web Services for the OpenAPI specifications.

Administration

The admin web service provides access to all administration commands supported by epadmin from a REST API.

Figure old-and-gone shows the results returned when executing the display node command from the help UI.

The display node command can also be executed using a command line tool like curl: 

curl --form "parameters=" --form "files="  --silent  --user admin "http://kapoho.local:8008/admin/v1/targets/node?servicename=A.X&command=display" | json_pp
Enter host password for user 'admin':
{
   "results" : [
      {
         "statusMessage" : [],
         "columnHeaders" : [
            {
               "columnType" : "STRING",
               "columnName" : "Node"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Node Name"
            },
            {
               "columnName" : "Node Description",
               "columnType" : "STRING"
            },
            {
               "columnName" : "Node State",
               "columnType" : "STRING"
            },
            {
               "columnName" : "Host Name",
               "columnType" : "STRING"
            },
            {
               "columnName" : "Administration Port",
               "columnType" : "STRING"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Discovery Service Port"
            },
            {
               "columnName" : "Discovery Service State",
               "columnType" : "STRING"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Node Directory"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Deployment Directories"
            },
            {
               "columnName" : "Install Time",
               "columnType" : "STRING"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Last Start Time"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Build Type"
            },
            {
               "columnName" : "Product Version",
               "columnType" : "STRING"
            },
            {
               "columnName" : "Product Installation Directory",
               "columnType" : "STRING"
            },
            {
               "columnName" : "Sensitive Configuration Data Encryption",
               "columnType" : "STRING"
            },
            {
               "columnType" : "STRING",
               "columnName" : "Secure Communication Profile Name"
            }
         ],
         "rows" : [
            [
               "[A.X]",
               "A.X",
               "No description",
               "Started",
               "Kapoho.local",
               "19188",
               "54321",
               "Running",
               "/opt/RUN/./A.X",
               "/opt/RUN/./A.X/deploy",
               "2019-11-23 07:23:04 -0800 UTC",
               "2019-11-23 15:29:23 -0800 UTC",
               "DEVELOPMENT",
               "TIBCO StreamBase Runtime 10.6.0 (build 1911231348)",
               "/opt/tibco/sb-10",
               "Disabled",
               "None"
            ]
         ],
         "serviceName" : "A.X",
         "returnCode" : 0
      }
   ]
}

Authentication

The admin web service performs authentication as described in Web Services. In addition, the underlying administration commands that are executed on behalf of the admin REST endpoint delegate authentication to the user that was created when the node was installed (see Default Security). The execution of the administration command depends on trusted host being enabled in the node administration realm (which it is by default).

Figure 1, “Admin web services authentication” summarizes the authentication process for the admin web service. Authentication consists of these steps:

  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. on a 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.

Admin web services authentication

Admin web services authentication

Healthcheck

The healthcheck web service provides a simple check for the current node status. The returned node status can be one of:

  • STARTED

  • STOPPED

Figure old-and-gone shows the results of the status command executed from the help UI.

The status command can also be executed using a command line tool like curl: 

curl --silent --user admin "http://kapoho.local:8008/healthcheck/v1/status" | json_pp
Enter host password for user 'admin':
{
   "nodeState" : "STARTED",
   "nodeName" : "A.X"
}

Metrics

The metrics web service provides access to all node and engine metrics from a REST API.

Figure old-and-gone shows the results returned when reading the builtin.node.transactions.latency.average.microseconds metric from the help UI.

A metric can also be read using a command line tool like curl: 

curl --silent --user admin \
  "http://kapoho.local:8009/metrics/v1/metrics/builtin.node.transactions.latency.average.microseconds" | json_pp
Enter host password for user 'admin':
{
   "description" : "Average transaction latency (microseconds) for node A.X",
   "lastUpdatedTimeStamp" : 1583539745,
   "name" : "builtin.node.transactions.latency.average.microseconds",
   "type" : "METER",
   "metric" : {
      "oneMinuteRate" : 173.391899996294,
      "fifteenMinuteRate" : 161.23666137742,
      "meanRate" : 162.895496120154,
      "count" : 301848,
      "fiveMinuteRate" : 155.835791024557
   }
}