Zum Hauptinhalt springen

Websocket

GET 
/websocket

Most operations at brokerize have asynchronous effects.

For example, consider the flow of an order: when the user creates an order, it will not immediately appear in order list endpoints, because usually brokers take a few seconds until they are retrievable in those lists. Also, after a while, the order may be executed or cancelled asynchronously by the stock exchange.

A common solution for frontends would be to reload the order list regularly. However data is then either delayed or there will be many more requests than needed.

The brokerize websocket endpoint allows getting updates via web sockets. Generally speaking, clients can subscribe by assigning a subscription id and will then receive updates on that subscription.

In this documentation, ⬆️ denotes messages from the client to the server, whereas messages from server to client are marked with ⬇️.

authentication​

When using cookies for authorization, the WebSocket connection is authenticated with the HTTP upgrade request.

If token headers are used, the first message from client to server must be:

⬆️ {
    "cmd": "authorize",
    "idToken": <string>
}

In all cases, clients must wait for the welcome message before sending other messages:

⬇️ { "cmd": "authenticated" }

ping​

After 1 minute of inactivity of a client, the WebSocket connection will be considered stale and will automatically terminated. To prevent this, a ping message can be sent:

 ⬆️ {"cmd": "ping"}

The server also sends this message regularly. If no message has been received on a WebSocket connection for more than 1 minute, it should be terminated by the client.

 ⬇️ {"cmd": "ping"}

subscriptions​

Subscriptions can be used to get invalidate events or updates for selected resources.

invalidate subscriptions​

Invalidation events can be used for the frontend to know when reload requests via the HTTP endpoints are appropriate. Currently only invalidate events can be subscribed, the actual data must then be reloaded using the HTTP endpoints.

To set up a subscription for an invalidate event, use:

⬆️ {
    "cmd": "subscribe",
    "type": "invalidate",
    "subscriptionId": 1,
    "entity: "brokersessions" /* "positions" | "orders" */,
    "portfolioId": 42 /* required for "positions" or "orders" */
}

If the subscription failed to be set up on the server, an error will be sent for the subscription. This also automatically ends the subscription on the server side:

⬇️ {
    "subscriptionId": 1,
    "error": {
        "message": "Could not set up invalidation event due to..."
    }
}

If an invalid subscriptionId is provided (or the subscription id is already in use by the connection), an error like this will be sent:

⬇️ {
    "error": {
        "message": "Could not add subscription due to invalid subscriptionId"
    }
}

⚠️ the connection will then be terminated immediately.

If the subscription is sucessfuly set up, whenever an invalidation happens, the server will send a message like this:

⬇️ {
    "cmd": "invalidate",
    "subscriptionId": 1
}

When that invalidation event is received, the client should reload the data using the corresponding endpoints.

Clients can end their subscription with the unsubscribe command:

⬆️ {
    "cmd": "unsubscribe",
    "subscriptionId": 1
}

subscribe to the state of a decoupled operation​

For decoupled operations (e.g. authorizing a session TAN using a second factor device), the state of the operation can be subscribed:

⬆️ {
    "cmd": "subscribe",
    "type": "decoupledOperationStatus",
    "subscriptionId": 1,
    "sessionId": string,
    "decoupledOperationId": string
}

Error handling as well as unsubscribing works as described for invalidate subscriptions. Example message from the server for updating the state:

⬇️ {
    "cmd": "updateDecoupledOperationStatus",
    "subscriptionId": number,
    "state": <DecoupledOperationStatus>
}

Responses​

Upgrading to WebSocket