LiveView Server REST API

Contents

REST API Supported Features and Usage
Running Queries on the LiveView Server Using REST API
REST API Source Documentation

For formal documentation on the REST API, you can:

  • Use the documentation locally installed with your Live Datamart installation at REST API Documentation.

  • Enter http://localhost:10080/lv/api/v1/ into a web browser when connected to a Live Datamart server instance.

You can also access the documentation using any method you use for viewing the Live Datamart documentation, such as:

  • docs.tibco.com

  • docs.streambase.com

  • the Help system in StreamBase Studio

REST API Supported Features and Usage

The REST API assists in the rapid development of LiveView queries due to its simplicity, such that it can be tested from a web browser. In essence, the browser is the client; using other LiveView clients such as LiveView Desktop or LiveView Web is not required.

The REST API facilitates integration into your environment due to its standard technology stack. As the REST API relies on standard HTTP, it is accessible from any language or toolkit that supports HTTP and JSON, such as JavaScript, Ruby, and Python.

In contrast to the other LiveView APIs listed here, which are client-side APIs, the REST API is exposed on the Live Datamart server side. This enables client development using your preferred language.

The LiveView REST API uses standard HTTP verbs to query and manipulate data. Through the API, you can:

  • Retrieve the details of a specific table, including options to only return tables with the given allowedPermission, or only return tables with the given type

  • Retrieve a list of all tables on the server

  • Retrieve the version of the current server

  • Delete specified tuples on the given table, with either a query or a list of tuples with keys

  • Retrieve streaming data

  • Issue a snapshot query on the given table, with optional query filter

  • Publish new list of tuples to a table

  • Check whether the query will parse, and if so, return the schema and parsed query

  • Manage alert rules, including:

    creating alert rules
    deleting alert rules
    retrieving alert rule information
    updating alert rules
    validating alert rules

API Usage Notes

Publishing using this API is intended for low-bandwidth embedded devices. It is not intended for high-bandwidth publishing, such as publishing millisecond-level data to a table.

Alert names are only required when creating alert rules. The name parameter is not required otherwise.

When updating an alert actions parameter, you must update all values in actions.

Running Queries on the LiveView Server Using REST API

The REST API documentation provides the parameters and syntax available for querying the Live Datamart server. Running the following query examples requires a connection to a LiveView server instance. These examples use localhost, with the LiveView default port of 10080, using this URL format and appending the parameters and syntax as required: 

http://localhost:10080/lv/api/v1/

Example 1: querying for the Live Datamart server version. Append /version to your URL and enter it into your browser:

http://localhost:10080/lv/api/v1/version

Example 1 results:

{"version":1.1,"build":"2.2.3"}

Example 2: Querying a Live Datamart system table. Append /tables/{tablename} to http://localhost:10080/lv/api/v1 and enter it into your browser: 

http://localhost:10080/lv/api/v1/tables/LVSessions

Example 2 results:

{"name":"LVSessions","schema":{"SID":"string","User":"string","Host":"string",
"QueryCount":"int","LastRequestTime":"timestamp","LastRequest":"string",
"ClientInfo":"string","Created":"timestamp","Type":"string","SessionTimeout"
:"long"},"tableGroup":"sys","shortDescription":"Session Information",
"reqClientCapabilities":[],"description":"Session information including 
remote host, recent activity","tableSpace":null,"capabilities":
["SNAPSHOT","CONTINUOUS","ALERT_RULES"],"queryLanguages":["LIVEVIEW"],
"keyFields":["CQSInternalID"],"indices":[["SID"]],"status":"ENABLED",
"statusMessage":"System Table","isSystemTable":true,"createTime":
1505503768698,"filter":null,"numServers":1,"rejectedServers":0,"
allowedPermissions":["table:list","table:query","table:ccquery","table:publish",
"table:delete","table:manage","table:add","table:remove","alert:list","alert:set",
"alert:delete","alertaction:email","alertaction:java","alertaction:oscmd",
"alertaction:publish","alertaction:sendtuple","alertaction:delete"]}

Example 3: Snapshot query for all tuple activity for a selected table. Append /tuples to the end of your table URL and enter it into your browser:

http://localhost:10080/lv/api/v1/tables/LVSessions/tuples

Example 3 results: (formated for clarity)

[{"type":"begin_snapshot","data":{"schema":{"SID":"string","User":"string",
"Host":"string","QueryCount":"int","LastRequestTime":"timestamp","LastRequest"
:"string","ClientInfo":"string","Created":"timestamp","Type":"string",
"SessionTimeout":"long"},"key_fields":["CQSInternalID"]}},

{"type":"add","key":1,"data":{"SID":"9afa5181-a622-4b93-9df0-22088d32390d","User":null,
"Host":"10.0.75.1","QueryCount":3,"LastRequestTime":1505503864683,
"LastRequest":"exec-query","ClientInfo":"AlertService_0","Created":
1505503864447,"Type":"STREAMING_BINARY_BIG","SessionTimeout":60000}},

{"type":"add","key":2,"data":{"SID":"c6d690d7-93d9-4780-8795-b6d68f8bbf66",
"User":null,"Host":"10.0.75.1","QueryCount":0,"LastRequestTime":1505503864720,
"LastRequest":"get-version","ClientInfo":"AlertService_Utility","Created"
:1505503864713,"Type":"STREAMING_BINARY_BIG","SessionTimeout":60000}},

{"type":"add","key":3,"data":{"SID":"d8134509-80e6-42cf-873a-8204797b53bf"
,"User":null,"Host":"10.0.75.1","QueryCount":6,"LastRequestTime":
1505503865729,"LastRequest":"exec-query","ClientInfo":"MonitorSystemTables",
"Created":1505503865411,"Type":"STREAMING_BINARY_BIG","SessionTimeout":60000}},

{"type":"add","key":4,"data":{"SID":"4b686640-68e4-4fad-aef6-07d78e96e884",
"User":null,"Host":"10.0.75.1","QueryCount":0,"LastRequestTime":1505503874349,
"LastRequest":"describe-tables","ClientInfo":"AlertActionProcessor0","Created"
:1505503874319,"Type":"STREAMING_BINARY_BIG","SessionTimeout":60000}},

...
]

Live Data Example

You can test the REST API to view live data generated from your Live Datamart server, in an event source client context. Testing is not meant for direct navigation to the API from a web browser, however. For example, if you append /live to your URL, the browser prompts you to download content that simply does not apply to the operation. To work around this, append /lviewer or another viewer to your query.

The following example demonstrates how to display live table updates for the LVSession table using the appended /lviewer. The /lviewer junction is a quick means to test live data and is not meant to be used outside of this example. TIBCO recommends using a proper client when not simply exploring the REST API.

  1. Connect to a Live Datamart server instance. For example, from StreamBase Studio, run the Hello LiveView sample and wait for the Live Datamart service instance to start.

  2. Open two browser windows.

  3. In window 1, enter http://localhost:10080/lv/api/v1/tables/LVSessions.

    Notice the table information is displayed.

  4. In window 2, enter this URL: http://localhost:10080/lv/api/v1/tables/LVSessions/tuples/lviewer (or any viewer from the /live URL).

    Notice in window 2 the live data for the session is displayed.

  5. In window 1, press F5 to refresh the browser. Notice the data in window 2 is updated.

  6. Close both browsers when finished.

REST API Source Documentation

Use this URL to view the open API source documentation: http://localhost:10080/lv/api/v1/doc.yaml. Note that a LiveView Server instance must be running in order to view the documentation.

Due to technical limitations, if you use Swagger to generate a client, the issueQuery operation must be written manually with a proper Server-sent Events (SSE) client. The Swagger-generated issueQuery operation does not support SSE.