Web-sockets client protocol

This section details the messages passed between the Service Gateway and a client application for streaming data.

Headers

Info

When establishing a WebSocket connection, the 'Sec-WebSocket-Protocol' header must be provided, unless authorization has been disabled.

header

value

details

Sec-WebSocket-Protocol

"Bearer <INSIGHTS_TOKEN>"

This can be obtained with the KXI CLI using the command kxi auth print-token. For more details refer to the obtaining an access token guide.

Query String

When establishing the connection, set the following query string parameters to determine the protocol used.

parameter

values

details

in

'json' or 'qipc'

The protocol of the messages sent from the client

out

'json' or qipc'

The protocol of the messages sent by the server

General message format

All messages are JSON or QIPC objects. Messages are either subscription requests and responses, or event messages. Event messages return data based on the subscription request. Subscription request messages may contain an optional response_id, which all corresponding response messages must contain.

The subscription request message contains the following fields:

field

type

details

type

string

The update type; either subscribe, snap, subsnap or unsubscribe. This field is expanded upon below

id

int

The ID of the individual message. The client must increment this number with each message sent. Replies from the server to a particular message contain the ID of the message it is responding to. There may be multiple responses to subscribe and subsnap messages.

error

int

Present in error response messages

payload

object

The payload for the particular message type

Subscription requests and responses

The update type is one of the fields in a subscription request sent by the client. In response to a subscription request message, you will receive an acknowledgment back. The update types are as follows:

type

details

response

subscribe

Incremental refreshes of the data. After the subscription response you'll receive update messages

subscribed

snap

A snapshot of the data will be sent

snapped

subsnap

A snapshot of the data followed by incremental updates. After the subscription response you'll receive update messages

subsnapped

unsubscribe

Stop the subscription to the data

unsubscribed

Subscribe

The subscribe message is sent by the client to the Service Gateway to request a stream of data.

Payload

name

type

required

details

topic

String

Yes

The topic to subscribe to

subTopic

String

No

The filter on the topic data. If this is empty all data for the topic is provided

Example

{
 "type":"subscribe",
 "payload":
 {
 "topic":"trade",
 "subTopic":
 {
 "ccyPair","EUR/USD"
 }
 },
 "id":1234
}

Subscribe response

The subscribed message is sent from the Service Gateway to the client in response to a subscribe message, if it was successful.

Payload

field

type

required

details

subscription

UUID

Yes

The id the SG has assigned to this subscription if set up successfully

Example

{
 "type":"subscribed",
 "payload":
 {
 "subscription":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 },
 "id":1234
}

Snapshot

The snap message is sent from the client to the Service Gateway to request a snapshot of the data.

Payload

field

type

required

details

topic

String

Yes

The topic to subscribe to

subTopic

String

No

The filter on the data. If this is empty, all data for the topic is provided

Example

{
 "type":"snap",
 "payload":
 {
 "topic":"trade",
 "subTopic":
 {
 "ccyPair","EUR/USD"
 }
 },
 "id":1235
}

Snapshot response

The snapped message is sent from the Service Gateway to the client in response to a snapshot message, if it was successful.

Payload

field

type

required

details

data

Object

Yes

The data in the snapshot, if the request was successful

Example

{
 "type":"snapped",
 "payload":
 {
 data:
 {
 "ccyPair":["EUR/USD","EUR/USD","EUR/USD","EUR/USD"],
 "val":[1.02,1.01,1.03,1.01]
 }
 },
 "id":1235
}

Subscription with snapshot

The subsnap message is sent from the client to the Service Gateway to request a subscription with a snapshot of the current state of the data in the response.

Payload

field

type

required

details

topic

String

Yes

The topic to subscribe to

subTopic

String

No

The filter on the data. If this is empty, all data for the topic is provided

Example

{
 "type":"subsnap",
 "payload":
 {
 "topic":"trade",
 "subTopic":
 {
 "ccyPair","EUR/USD"
 }
 },
 "id":1236
}

Subscription with snapshot response

The snapped message is sent from the Service Gateway to the client in response to a subscription, containing the snapshot message and current state of the data, if it was successful.

Payload

field

type

required

details

data

Object

Conditional

The data in the snapshot, if the request was successful

subscription

UUID

Conditional

The id the SG has assigned to this subscription if it was set up successfully

Example

{
 "type":"subsnapped",
 "payload":
 {
 data:
 {
 "ccyPair":["EUR/USD","EUR/USD","EUR/USD","EUR/USD"],
 "val":[1.02,1.01,1.03,1.01]
 },
 "subscription":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 },
 "id":1236
}

Unsubscribe

The unsubscribe message is sent from the client to the Service Gateway to terminate a subscription stream.

Payload

field

type

required

details

subscription

UUID

Yes

The id of the subscription to be stopped

Example

{
 "type":"unsubscribe",
 "payload":
 {
 "subscription":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 },
 "id":1237
}

Unsubscribe response

The unsubscribed message is sent from the Service Gateway to the client to confirm the subscription has been terminated.

Once this message is received, no more data is sent for the given subscription id.

Payload

The payload is empty for this message.

Example

{
 "type":"unsubscribed",
 "payload":
 {
 "subscription":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 },
 "id":1237
}

Event messages

After sending a subscription request and receiving the response, you will start to receive data updates. These updates are driven by the subscription request. If there are updates to the data that you have requested, these updates will be sent to the client every 5 seconds.

name

direction

details

update

Server -> Client

Continuous response to subscribe or subsnap messages

error

Server -> Client

Message sent if an error occurs when processing a command

Update

The update message is sent every 5 seconds from the Service Gateway to the client in response to a subscribe or a subsnap message.

Payload

field

type

required

details

data

Object

Yes

The data in the snapshot, if the request was successful

subscription

UUID

Yes

The id the SG has assigned to this subscription if it was set up successfully

Example

{
 "type":"update",
 "payload":
 {
 data:
 {
 "ccyPair":["EUR/USD","EUR/USD","EUR/USD","EUR/USD"],
 "val":[1.02,1.01,1.03,1.01]
 }
 "subscription":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 },
 "id":1236
}

The id refers to the message id from the client that set up the subscription.

Error response

The error message is sent from the Service Gateway to the client if an error occurred when processing a command.

Payload

The payload is empty for this message.

Example

Example:

{
 "type":"error",
 "id":1234,
 "error":29
}

Error codes

code

details

20

No type

21

Payload not present

22

Payload invalid

28

Bad or no id provided

29

id is equal to or less than the last one seen on this connection

42

Already subscribed

43

Not subscribed

61

Incorrect data type received

62

Failed to provide all required inputs

63

Provided topic does not exist for subscription

64

Not all subscription topics provided as valid keyed tables