WebSocket API concept
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 HTTP.
The WebSocket connection must be initiated by the external system. WebSocket handshake is supported for requests to special URLs:
-
user-api –
/ws, requires authorization. Serves client connections from system users. -
token-api –
/ws/token/v1/:TOKEN, where:TOKENis the identifier from thetoken_localfield of the integration_point entity. Does not require authorization; its presence replaces it. Serves integration connections from external services and systems.
Message format
All messages use the JSON array format with two elements:
["method",{... params ...}]
If the method is a request, it:
-
must contain the
qidparameter with a unique identifier of arbitrary type for matching with the response. -
expects a response
["method_result",{… params …}]containing the sameqidand protocol-defined parameters, in particularresult.
If the method is an asynchronous message, it can be formatted as a request with a response that only confirms receipt, or may not expect a response at all. The qid parameter is then optional.
Connection setup
Initially the server supports only the basic methods login for authorization and setup for connection setup.
Any other methods are unavailable, and the server returns an error when they are requested.
For the connection to gain functionality, it must be configured with the setup method.
["setup",{"qid":0.5828120205227802,
"capabilities":[{"key":"a"},
{"key":"b"}] }]
["setup_result", {
"qid":0.5828120205227802,
"capabilities":[
{"key":"a","result":"ok"},
{"key":"b","result":"error","errormsg":"Unknown capability"}] }]
Within user-api the request message may contain optional parameters:
-
params- additional connection settings used by some APIs. -
appPath- relative URL of the user application that made the connection.
["setup", {"qid":0.34198798,
"capabilities":[{"key":"a"},{"key":"b"}],
"params":{"x":1,"y":"abc"},
"appPath":"/app/arm" }]
The various connectable APIs specified in the capabilities property are filtered by the server.
Filtering is based on:
-
a) discovered modules,
-
b) configured endpoints in the IAM service metadata (assets iam_all.json and iam.json),
-
c) assigned roles of the authorized user.
For all APIs that fail the filter, information about the failure reason is returned in the response.
After the required APIs are successfully connected, all methods of these APIs become available to the connected application or system within the configured WebSocket connection. The connected APIs also begin supplying server events.
If the setup method is called before authorization (within user-api), all capabilities return "ok" in its response, but after authorization the server sends a modified capabilities list in response to the login request.
When calling methods of APIs that are not connected, a response with the error "Unknown/restricted method" is returned.
See also
-
Script component "WebSocket connection operation"
-
REST API: /rest/v1/fs/targets/websocktemp