IAP/WS Fundamentals

Owned by Nina Cardillo
29-Sept-2023
2 min read

The IAP/WS API uses WebSockets to support two-way communication between client apps and the SmartServer. Unlike REST, which requires the client to poll and then wait for a response, the WebSocket API allows you to get real-time updates from the SmartServer.

To use the WS API (or REST API), you will first need to log into the CMS using /iap/auth/login request. The login response will have a cmsSID cookie that is needed in the request header for all subsequent REST or WS requests.
 
To use a WebSocket, you do a WebSocket request, and a WebSocket is then opened and one or more WebSocket updates are sent from the SmartServer to the client.

WebSockets are used in two ways:

  1. A general purpose WebSocket that is used to get datapoint updates, device state changes, and alarms and other general purpose updates similar to what you see in the CMS Web pages.

    1. This WebSocket is opened and typically stays open during the entire time your Web page is open.

    2. Use a REST API subscribe request to select the datapoints you want to see updates.

      1. Datapoint updates will occur due to ON-demand GET requests (a REST API request), polling (Datapoint Properties Widget), or anything that causes a datapoint event.

    3. While the WebSocket is up the SmartServer will also send updates for many of the features seen in the CMS updates, such any device state changes or alarm changes.

      1. These are the warning and error messages that you see in the upper right-hand corner of the CMS Web page 

  2. A data log WebSocket is used to get data logs from the SmartServer.

    1. This WebSocket is opened only long enough to process the request and is automatically closed by the SmartServer after sending all data log entries.

    2. An “end” update indicates that there is no more information and the WebSocket will close.

      1. If there are no data logs for the specified request duration or the listed datapoints then all you will only get an “end” update.

      2. If there are data logs then you will get a single update for each data log entry, followed by “end” when there is no more data available.

Note: For a single user login, only one web page that uses WebSockets (CMS or custom web pages) should be opened at a time, otherwise only one web page may see datapoint updates. This may happen as all Web pages for the same user login see the same datapoint updates and there is only one datapoint subscribe list per user login. To have more than one WebSocket Web page open at a time, we recommend logging into the Web pages using different user logins.