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":
  {
    "topic":"trade",
    "subTopic":
    {
      "ccyPair","EUR/USD"
    },
    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