WebSocket API

WebSocket is an alternate transport to getting data from the server. The process of notification about events occurs from the server to the client through a constantly open connection. This allows you to display changes in real time.

Currently the Atmosphere Framework used as an application layer library and protocol.

Let's describe standard workflow for WebSocket API:

• Determine URL to API calls:
  
      1- for iTrack ServerMate it will be http(s)://api.itrack.live/v2/
    2- for On-Premise instances it will be http(s)://api.your.domain/


• Authorize with user/auth(...). This API method will return the hash you should use for all your next API calls.
• Open WebSocket connection by the path /event/subscription/ with Atmosphere protocol parameters.
• Subscribe on events using subscribe action.
• Listen and process the incoming events.
• Get the current tracker states after subscribe on a state event.
• Subscribe and unsubscribe on the events if needed.
• Unsubscribe when leaving monitoring page using unsubscribe action.

Note what:

• The subscription requests must contain the hash parameter gotten by user/auth action.
• Responses and errors for the subscribe and unsubscribe actions are similar with common API format.
• All WebSocket frames use a JSON format. Exceptions are heartbeat frames containing 'X'.

In a simplified form, opening a websocket using atmosphere-javascript looks like this:

   var request = {
      url: 'https://domain.com/event/subscription',
      contentType: "application/json",
      transport: 'websocket'
   };    atmosphere.subscribe(request);

Executing this code will lead to send a request

ws://domain.com/event/subscription?X-Atmosphere-tracking-id=0&X-Atmosphere-Framework=2.3.6-javascript&X-Atmosphere-Transport=websocket&Content-Type=application/json&X-atmo-protocol=true

and upgrade the connection to websocket. After what will be sent a first frame through opened websocket channel:

b623a15d-9623-4fd8-a9d3-697036635c29|30000|X|

This is service message for the Atmosphere protocol negotiation. Now everything is ready to subscribe on events.

All of messages from client side contain field 'action' with action name (e.g. "subscribe" or "unsubscribe").

All of messages from server side contain field 'type' with message type ("event", "response" or "error") and data with a payload.