Getting Started

Overview

The platform provides a simple websocket/JSON-based API for access to platform functions supporting accounting and trading processes.

Client libraries for integrating with websocket applications exist in python, javascript, Java, and many other languages.

This document refers to a canonical asynchronous message passing model of a websocket:

    ws = new Websocket(endpoint);
    ws.onOpenCallback = () -> { print “Connection establish”; };
    ws.onMessageCallback = (msg: string) -> { print “Received a message: “, msg; };
    ws.onErrorCallback = (err: Error) -> { print “Error!”, err; };
    ws.onCloseCallback = () -> { print “Connection closed”; };
    ws.connect();
    ws.send(payload);

This model can be found in some variation in most client libraries, and manages passing of simple message payloads, typically as either raw binary or string data.

The platform API sends, and expects to receive, JSON message payloads: messages should be serialised to JSON (stringified) before sending, and parsed from the incoming string on receipt.

This document will refer to the JSON representation of outbound messages (sent to the platform) and incoming messages (received from the platform).

Download firecamp ws collection

Firecamp collection

Establishing a connection

The specific API endpoint will be provided to you on request. It will have the form:

wss://api.etana.com/ws/

On making a connection to the API endpoint, the service can be queried for heartbeats in order to confirm that a healthy connection exists:

Request:

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "chanId": 1,
    "item": "heartbeat"
  }
}

Response:

    {
        "id": 1,
        "result": {
            "chanId": 1,
            "item": "heartbeat"
        }
    }

    {
        "chanId": 1,
        "data": 1542377336
    }

    ...

This demonstrates the general form of a request/response interaction with the service, and the behaviour of a subscription.

Submitting an API request

In general API requests are synchronous request/response interactions, handled asynchronously.

A request is codified as a JSON object with the following properties:

Field	Type	Description
id	number/string	(optional) A client-side identifier for the request that is returned on the response so the client can correlate the response event with the original request.
method	string	The API request method name.
params	object	A JSON object containing parameters specific to the API request.

The response is a JSON object as follows:

Field	Type	Description
id	number/string	The client-side identifier from the original request.
result	object	The result specific to the request made, assuming the request completes without an error. If this field is present, the error field will be absent.
error	object	An object representing an error if one occurred. Present if the API call fails (the result field will be absent).

Clients may implement a request/response interaction by providing a client-side identifier on the request message, and then waiting for the response message with the matching identifier.

Each API detailed will focus on the method requests (and associated parameters), and the responses to these method requests.

Subscriptions to asynchronous streams

A subscription is set up using a specific set of API request/response calls.

The initial subscription method specifies the item to be subscribed, and sets up a stream of asynchronous messages on an client-specified “channel”.

On receipt of this API request, the platform will send additional messages, asynchronously, conforming to the subscription request. Asynchronous channel messages are JSON objects with the following properties:

Field	Type	Description
chanId	number	The client-side channel identifier specified as part of the subscription.
data	object	A subscription specific JSON object representing the asynchronous update.

In order to unsubscribe, or close down a subscription channel, the unsubscribe method must be called.

Subscribe a channel for updates on a particular item

Request channel updates for a subscribable item, including qualifying parameters.

Request method

subscribe

Parameters

Field	Type	Description
chanId	number	A client-side identifier that is returned on asynchronous stream messages to identify the channel that those messages belong to.
item	string	The name of the item to be subscribed to.
...	``	Additional parameters to qualify the subscription.

Response

Field	Type	Description
chanId	number	The client-side channel identifier specified in the subscription request.
item	string	The name of the item subscribed to.

Unsubscribe from updates on a channel

Request method

unsubscribe

Parameters

Field	Type	Description
chanId	number	The client-side channel identifier to be unsubscribed.

Response

Field	Type	Description
chanId	number	The client-side channel identifier unsubscribed.