Categories:
OpenAPI
Introduction
Requests & Responses
UPDATED
Pelican Wireless Systems provides a comprehensive API for interacting with their devices and services. Understanding how to properly structure requests and interpret responses is crucial for effective integration. Below is an overview of the request and response mechanisms within the Pelican API.
Requests
All API requests must be sent over HTTPS to ensure secure communication. Each request should include the following six elements:
username – The email ID of a valid Pelican Site Manager user. This ID is created through the administrative interface of the Pelican Web App.
password – The password associated with the specified email ID. Since the Pelican system enforces SSL connections, the password is automatically encrypted for each request.
request – Specifies the type of request being made, either set or get. get requests retrieve current values of attributes, while set requests modify attribute values.
object – Indicates the type of object to which the get or set is applied. Supported object types include:
- Thermostat-related: Thermostat, ThermostatSchedule, SharedSchedule, ThermostatHistory, ThermostatEvent, ThermostatUsage.
- Power Control Modules: PowerOutput, PowerSchedule.
- MySites: Sites.
- User Management: User.
- Notifications: Notification.
- Demand Response: Site, DemandResponseHistory.
- PowerLink: PowerUsage.
selection – A set of attribute/value pairs used as a query match for the set or get request. In a get request, items matching the selection are returned in the XML reply. In a set request, items matching the selection are modified in the Pelican system. Pairs are separated by semicolons (;), and attributes are separated from their values by colons (:). Attribute names are not case sensitive; attribute values are case sensitive.
value – For get requests, this is a semicolon-separated list of attributes being requested. For set requests, it’s a semicolon-separated list of attribute/value pairs to be modified. Attribute names are separated from their values by a colon (:). Semicolons and colons are invalid characters for either the attribute or the value. Attribute names are not case sensitive; attribute values are case sensitive.
When using HTTP GET, the six required elements must be formatted using standard HTTP notation, with the element name followed by an equal sign and then the element’s value. The first element is preceded by a question mark ?, and elements are separated by the ampersand & character. Standard HTTP character escaping is supported. When using HTTP POST, standard encoding is supported.
Responses
API responses utilize customary HTTP status codes, with the most typical ones being:
- 1: Success.
- 0: Failure.
Sample Request
There are currently 14 object directories supported by the Pelican API. Attribute names are not case sensitive. Attribute values are case sensitive.
The web address of the API interface is the full web address of the site followed by “/api.cgi”. Therefore, a valid API request would be as follows:
To retrieve specific thermostat settings, you might send a request like:
GET
https://demo.officeclimatecontrol.net/api.cgi?username=myname@gmail.com&password=mypassword&request=get&object=Thermostat&selection=name:TestThermostat;&value=heatSetting;coolSetting;temperature;
Sample Successful Response
If the request is successful, the response might be:
<xml version="1.0" encoding="UTF8"?>
<result>
<Thermostat>
<name>TestThermostat</name>
<heatSetting>68</heatSetting>
<coolSetting>72</coolSetting>
<temperature>70</temperatur>
<Thermostat>
<success>1</success>
</result>
Sample Failure Response
If the thermostat “TestThermostat” is not found, the response might be:
<?xml version="1.0" encoding="UTF8"?>
<result>
<success>0</success>
<message>No thermostats found matching selection criteria.</message>
</result>
By adhering to these request and response structures, developers can effectively interact with Pelican’s API to manage and monitor their HVAC systems.