Skip to content

Web-sockets client protocol

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

Headers

When establishing a web-socket connection the following headers must be specified:

header value details
Content-Type "application/json" Future definitions will be based on the format of the data being sent in
Accept "application/json" Future definitions will be based on the format you wish to receive

General message format

All messages are JSON objects. Messages are either subscription requests and responses or event messages. With event messages you would receive data back based on the subscription request. Subscription request messages may contain an optional "response id", which all corresponding response messages need to 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 This must be an incrementing number, and in the replies it must match the id of the request that the message is a response to
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