IAP API Fundamentals

Owned by Sacha Parisot (Unlicensed)
03-Jun-2022

The IoT Access Protocol (IAP) is an open and extensible protocol designed for the loT to provision and manage IoT devices, to access and update data from the devices, and to leverage the power of big data and AI with IoT-friendly interfaces to cloud services.  IAP defines three APIs:  IAP/MQ, which uses MQTT (Message Queuing Telemetry Transport) as the transport protocol, IAP/REST, which uses HTTP and HTTPS, and IAP/WS which uses WebSockets.

  • IAP/MQ is the IAP API based on MQTT version 3.1.1.  MQTT is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based messaging protocol. It works on top of the TCP/IP protocol. It is a lightweight protocol that is suitable for implementing applications, services, and drivers on a wide range of devices and servers including small code footprint edge devices, edge servers, and cloud hosts. IAP/MQ is used to connect services and drivers within an edge server, and is used to connect edge servers to each other and cloud applications and services.

  • IAP/REST is the IAP API based on REST (REpresentational State Transfer), or RESTful, web services.  REST web services provide an interoperable web-standard interface for web clients such as web-page scripts running in web browsers to communicate over HTTP or HTTPS with services hosted on web servers.  IAP/REST is typically used to connect client applications running within web-page scripts to an IAP/REST server, and can be used to implement any application supporting REST requests and responses.

  • IAP/WS is the IAP API based on WebSockets.  WebSockets is a communication protocol for persistent, bi-directional, full-duplex TCP connection from a user's web browser or application to a server. WebSockets allows the SmartServer to provide updates to the user in real time without having to always do a request.  WebSockets is typically used to get fast datapoint value changes, device status, and alarms in real time. It is also used to get data logs typically faster than using the REST API responses.   

To use IAP/REST or IAP/WS you will need to log into the SmartServer CMS using the IAP/REST Login and then use the CMS cookie in subsequent requests.  After logging into the CMS, you can issue IAP/REST or IAP/WS requests. There is no login for IAP/MQ.  IAP/MQ is controlled by enabling or disabling the IAP/MQ ports.

Special characters in IAP/REST and IAP/WS requests need to be encoded before sending the request to the SmartServer. The characters that are considered special characters, and where they are considered special, is different in IAP/REST and IAP/WS.

This introduction to the three APIs includes the following sections: