HTTPS based API

Modified on Tue, 26 Sep 2023 at 05:36 AM

HTTPS based API¶

The smartengine Application Programming Interface (API) provides two-way communication with the smartengine installation and other systems and applications. The API enables computers, smartphones, and tablets to access smartengine sensor network data and lighting controls. This API is available over HTTPs protocol with JSON framing for objects in two forms:

A simple REST¹ form of API can be used to easily get the sensor data.
A richer and more flexible Unified API² provides enhanced capabilities like subscribing for changes (instead of polling) to values of attributes as well as bulk processing.

Note

The HTTP(s) based APIs are enabled by default, but requires authentication as a known user in the system only. The API is not available using HTTP only unless it is explicitly configured in Network Services tab of the System Settings section of the Commission System application in smartmanager.

Access Control¶

All API requests must be authenticated through the web server using basic authentication. While you may use any of the configured userids (with their password), it is advisable to create dedicated user ids for external systems that communicate using the API.

Tip

You may configure users with API role which can be used to access the APIs only. This can be set up in the Users tab of the System Settings section of the Commission System application in smartmanager.

Accessing the REST API

You can perform a read request via the HTTP GET method, and you specify the database schema via a URI:
```
https://smartdirector-ip-address/rApi/resource-URI
```
Additional semantics are passed via URI parameters.
The response contains a JSON-framed object representing the database object referenced by the URI.
If the URI is invalid, an HTTP 404 error is returned.

Accessing the Unified API

You access the API via the HTTP POST method with a full JSON-framed request object
https://smartdirector-ip-address/uApi
The request object encapsulates the type of request (get or set) and the database schema components.
The response is a JSON-framed response object containing the request type results, possible error conditions, and possible elements within the schema is returned.
Only synchronous requests are supported.

URI Naming¶

You may address the individual elements of the Data Model³ through the REST API. Each element of the Data Model can be uniquely named as a relocatable URI, referred to as a ResourceURI.

URI Examples

You can retrieve the entire data model using the following URL. With the REST API, you can omit this when requesting the entire data model (the following two URIs are equivalent). But for all further attributes of the data model, a trailing / (slash) is not supported
```
https://smartdirector-ip-address/rApi
https://smartdirector-ip-address/rApi/
```
Use the following URL to get the name of the smartdirector cluster
```
https://smartdirector-ip/rApi/name
```
Use the following URL to get the array of locations. The REST API returns a JSON array of all location objects.
```
https://smartdirector-ip/rApi/location
```
Use the following URL to get the object corresponding to location 100. The REST API returns a JSON object with the attributes for the location.
```
https://smartdirector-ip/rApi/location/100
```
Use the following URL to get the string corresponding to trigger type attribute of a specific policy trigger named foobar, which itself is contained in a location object with the ID 100.
```
https://smartdirector-ip/rApi/location/100/policyTrigger/foobar/type
```

Operations¶

The REST API has the following capabilities -

Use GET HTTP request to fetch the values of attributes
Use PUT HTTP request to set the value of an attribute
JSONP Callback support for GET requests. To enable cross-domain applications, the smartengine REST API supports JSONP callback functionality with response framing that is enhanced to facilitate asynchronous clients. Additional data specified in the query string is ignored, but included in the JSONP response.
Search can be also be performed (case sensitive and exact match) using the GET requests

The Unified API can be accessed by sending HTTPS POST request to the following URL. The request and responses in this case are structured as JSON framed objects with the actual operation (get, set, subscribe, unsubscribe) being encapsulated with the associated data in the JSON object.

https://smartdirector-ip/uApi

The data model is identical to the one for REST API, but this interface supports the publish-subscribe capability which can be significant advantage over polling with GET requests one would have to do with REST API.

A subscription request results in an ongoing sequence of responses. The initial response is similar to the response to a get request. It returns the current state of the data model components the request is being made on. All further responses specify incremental or ongoing changes to the data model components and are cumulative (i.e each further response reflects a change from the overall data model state resulting from the application of all earlier responses).

For details of the REST API click here ↩
For details of the Unified API click here ↩
For details of the Data Model for smartengine click here ↩