Product Quotes WebSocket subscription walkthrough


1. Connection to the WebSocket

In order to connect to the WebSocket it is required first to pass the handshake handler with a valid access token.

Examples:

Java
// using netty-all 4.1.33
final WebSocketClientHandler handler =
new WebSocketClientHandler(
WebSocketClientHandshakerFactory.newHandshaker(
uri, WebSocketVersion.V13, "", false, new DefaultHttpHeaders()
.add("Authorization", "Bearer " + BEARER_TOKEN), MAX_FRAME_SIZE));


Python

import asyncio
import websockets
...
async with websockets.connect(url, extra_headers={'Authorization' : 'Bearer ' + bearerToken}) as websocket:
...


(image taken from WSO2)


Once connected to the WebSocket API, it is possible to subscribe for receiving product quote updates. Notice that if no subscription is requested, no product quote update will be received.

Important: ensure your client is not disconnecting and reconnecting every minute to websockets. The idea of Websocket is to establish one connection, subscribe to product quotes and then receive product quotes in real time as long as the client needs it.

Once a websocket connection is established, there is no need to reestablish the connection every time the access tokens are renewed. The websocket connection can work for hours and even days (there is no current limit for their expiration).


2. Subscription

Product Subscription request:

// subscription request
{
   "op": "subscribe",
   "productNames": [ productNames ]
}

// response
// the products returned are the products requested which were successfully added. 
{
   "op": "subscribed",
   "status": OK | WARN,
   "timestamp": epochTimestamp,
   "products": [ {"productName": ..., "quote": ... } ]
}

// response-failure
{
   "op": "error",
    "opRequest": "subscribe",
   "msg": ERROR_MSG,
   "code": ERROR_CODE
}

Important: in the list of product names for subscription it is recommended to don't send more than 100 product names per request. In order to subscribe to more than a hundred of products, it is possible to send several subscribe messages with different lists of product names.

In fact, It is recommended to don't subscribe to more than 15 DARWINs. Notice that your client accepts 50 requests / minute. Therefore, in the event of receiving too many quote updates, it will stop sending quotes until the following minute.


3. Unsubscription

Once subscribed to products, it is possible to unsubscribe from them. There could be an unsubscription from several products or from all.

// request
{
   "op": "unsubscribe",
   "productNames": [ productNames ]
}


{
   "op": "unsubscribeAll"
}

// response
// the productNames are the product names with effective unsubscription
{
   "op": "unsubscribed",
   "status": "OK",
   "timestamp": epoch,
   "productNames": [ productNames ]
}

// response-failure
{
   "op": "error",
    "opRequest": "unsubscribe""unsubscribeAll",
   "msg": ERROR_MSG,
   "code": ERROR_CODE,
   "timestamp": epoch
}


4. Product Quotes

New product quotes will be received for subscribed products.

{"op": "pq", "productName": fullProductName, "quote": quote, "timestamp": epochTimestamp}


5. Heartbeats

There will be a heartbeat being sent from the server periodically to detect if the WebSocket is still opened and working.

{"op": "hb", "timestamp": epochTimestamp}


6. Ping-Pong messages

In addition to the previous requests, the WebSocket client can send a ping message in order to detect if the server is still working as expected. The answer to the ping message will be a pong with the message received in the server and the timestamp of its processing.

// request (client side) . Msg is free text. 
{
   "op":"ping",
   "msg": "1234"
}

// response
{
   "op":"pong",
   "timestamp": 1511545528111,
   "msg": "1234"
}
Possible error codes:
ERROR CODE Mensaje
EMPTY_MESSAGE_RECEIVED Empty message received.
MESSAGE_NOT_RECOGNIZED
  • Event (typeEvent) in message (message) not recognized.
  • Message (message) is not recognized.
  • (typeEvent) not implemented.
PRODUCT_NOT_VALID No active product found with the name (productName)
MAX_PRODUCT_SUBSCRIPTIONS_REACHED Not allowed to subscribe to more than 10.000 products.