xStore Developers

Step 1. Understand what might go wrong

API servers work with TCP connections, which have to be maintained by all network infrastructure components that are involved on the way from the client program to our servers. This means that any glitch in the infrastructure can lead to connection instability. Of course, we are doing our best to ensure flawless operation, but even with perfect servers there will be components (firewalls, routers, cables and so on) that we do not control. If you plan to develop an application that has to work reliably for long periods of time, keep in mind that the following things might occasionally happen:

• Servers might not be reachable.
• Already established connections can be abandoned by network infrastructure due to overloading, being idle or for other reasons.

You will certainly want to detect such events and react properly, so:

Step 2. Learn about our server infrastructure

For redundancy reasons we have more than one server, each located in a different physical location (different data center). The list of available servers is always described in the API documentation, so check periodically if there are any changes.

You can connect to any one of the servers in the list, as they offer identical services and they refer to the same state of your trading history.

This also means that if you fail to connect to some chosen server, you can try another one from the list.

Our servers are managed in the load-balancing manner and the client is involved in some of this load-balancing machinery. In particular, if you attempt to log in you might get successful confirmation if everything is fine and then you can continue by executing any of the API functions, but you might as well get failure confirmation with the redirection phrase (see the API documentation for the exact syntax) that will direct you to another, less loaded server. You should then retry your login attempt on that other server. Note that our wrappers do that automatically and transparently.

Step 3. Keep your connections alive and in good shape

In order to reasonably manage system and network resources both servers and network infrastructure components (firewalls, etc.) are designed to deal with abandoned connections. This "dealing" is quite simple: those connections that do nothing for a longer period of time are considered dead and are dropped. In other words, the communicating computers are supposed to... communicate!

This sounds easy, as the major reason to connect to our servers is to execute some functions, right? This is true in general, but not necessarily for applications that work over long period of time, which can themselves have some periods of communication inactivity. In particular, this is essential for those applications that log in and then establish parallel streaming connection for subscriptions, leaving the first connection (those that was used to log in) somewhat unused.

In order to fulfill the requirement to "communicate" without any other business-level reason to do so, our servers offer the "ping" function that does not interfere with your trading activities, but is enough to refresh internal state of all the components on the way.

We recommend that if your application has no other reason to execute anything, it should call the "ping" command at least once per 10 minutes. This will ensure that your connections will never be considered stale.

The "ping" command is also a valid way to check whether the connection itself is indeed still alive.

Step 4. Monitor the subscription stream

For those applications that work with streaming subscriptions it might be useful to check whether the streaming connection is still alive. This is particularly important for those client programs that subscribe for low-frequency events, as there can be long periods of silence on the wire between subsequent data packets.

There is no "ping" command for the streaming connection - or rather there is its inverse form, the "keepAlive" message. It works the following way: the client program can subscribe for the "keepAlive" packets and the server will ping that client program with periodic "keepAlive" notifications. This way the client program can detect connection problems if there is no "keepAlive" packet arriving for some longer period of time.

We promise to send one "keepAlive" packet more or less every 3 seconds - use that guarantee to check whether the stream is still working even if the actual information you have subscribed to changes rarely and you do not get any news for long periods of time.