Concept Websocket API

Table of Contents

Overview
See also

Overview

Connection address

Any web server can be used to connect to the system via websocket. The same address and port are used as for the HTTP.

The websocket connection must be initiated by an external system. Websocket handshake is supported by requests for special URL:

user-api – /ws, requires authorization. Serves client connections from system users.
token-api – /ws/token/v1/:TOKEN, where :TOKEN is an identifier from the token_local field of the entity integration_point. Does not require authorization, it is replaced by the presence of :TOKEN. Serves integration connections from external services and systems.

Message format

All messages are in a two-element json array format:

["method",{... params ...}]

If the method is a query, it:

must contain a qid parameter containing a unique identifier of an arbitrary type to be mapped to the response.
suggests a response ["method_result",{… params …}] containing the same qid and protocol-defined parameters, in particular result.

If the method is an asynchronous message, it may be a request with a response that only acknowledges receipt, or it may not assume a response at all. The qid parameter is optional in this case.

Connection setup

Initially, the server supports only the basic methods login - for authorization, and setup - for connection setup. Any other methods will not be available and the server will return an error if they are requested.

In order for the connection to become functional, it must be configured using the following method setup.

Request message:

["setup",{"qid":0.5828120205227802,
          "capabilities":[{"key":"a"},
                          {"key":"b"}] }]

Message-Response:

["setup_result", {
   "qid":0.5828120205227802,
   "capabilities":[
     {"key":"a","result":"ok"},
     {"key":"b","result":"error","errormsg":"Unknown capability"}] }]

As part of user-api, the request message may contain optional parameters:

params - additional connection settings used by some API.
appPath - The relative URL of the user application that made the connection.

For example:

["setup", {"qid":0.34198798,
           "capabilities":[{"key":"a"},{"key":"b"}],
           "params":{"x":1,"y":"abc"},
           "appPath":"/app/arm" }]

The various pluggable APIs specified in the capabilities property are filtered by the server. Filtering is done on the basis of:

(a) Detected modules,
b) configured endpoints in the IAM service metadata (iam_all.json assemblies and iam.json),
c) the assigned roles of the authorized user.

On filtered APIs, the response will return information about the reason for the failure.

After the required APIs are successfully connected, all methods of these APIs become available to the connected application or system within the configured web socket connection. The connected APIs also start to supply server events.

If the setup method is called before authorization (as part of user-api), all capabilities return "ok" in response to it, but after authorization, the server will send a modified list in response to the login request capabilities.

Concept Websocket API

Overview

Connection address

Message format

Connection setup

See also