REST API

Starting with version 1.4, the Smart Building Automation system provides a REST API at "http://[Smart_Building_Automation_IP]/api". The following steps are required to use the REST API.

Preparation

  • Navigate to "all apps" – "settings" – "rest service" in the user interface of the Smart Building Automation system.
  • Enter the credentials and generate a hash. Save the generated hash, as it is required for the next step.

Authentication

Authentication is required to send requests to the REST API. A token is used for this purpose and is provided after a successful login via the REST API.

  • Send a POST request to "http://[Smart_Building_Automation_IP]/login" with the following header parameters:
    • x-elocs-username: [Username]
    • x-elocs-password: [Hash]

The token x-elocs-token is returned in the response and automatically set as a cookie. It is used to authenticate all subsequent requests.

Depending on where the requests to the Smart Building Automation system are sent from, the cookie is used automatically. Otherwise, the token must be included in the header of every request: Cookie:token=[Token].

Requests

The Smart Building Automation REST API can be used to retrieve the current status of individual functions within the system and to control them. The following requests are available:

GET: apps
"http://[Smart_Building_Automation_IP]/api/apps"
Returns a list of all apps.

GET: apps/{fullName}
Returns detailed information about the requested app.

GET: instances
Returns a list of all instances.

GET: instances/{instanceId}
Returns detailed information about the requested instance.

GET: instances/{instanceId}/{action}
Returns the current value of the requested property of a specific instance, for example, the current state of a light.

POST: instances/{instanceId}/{action}
Calls a method of the specified instance.

A test interface is available at "http://[Smart_Building_Automation_IP]/api", where all listed requests can be tested.

Examples

The following example shows how to switch a light using the REST API.

First, the required authentication steps must be completed (see the "Preparation" and "Authentication" sections). The resulting token can then be used to send the required requests and commands.

First, a GET request is sent to "http://[Smart_Building_Automation_IP]/api/instances". The response contains a list of all instances currently available in the Smart Building Automation system.

{
  "statusCode": 200,
  "statusText": "success",
  "data": [
    {
      "ID": "SC1_M04.Light1",
      "ClassName": "SmartCOM.Light.Light",
      "Name": "Roomlight",
      "Group": "AreaOutdoor"
    },
    ...
  ]
}

Since a light is to be switched, "Roomlight" is selected. Its "ClassName", "SmartCOM.Light.Light", can then be used to send a GET request to "http://[Smart_Building_Automation_IP]/api/apps/SmartCOM.Light.Light" and retrieve the available methods and properties.

{
  "statusCode": 200,
  "statusText": "success",
  "data": {
    "methods": [
      {
        "parameter": [],
        "name": "SwitchOn",
        "type": 0,
        "derived": false,
        "tags": [
          "linkable"
        ],
        "returnType": "void",
        "description": "switch light on",
        "isStatic": false
      },
      ...
    ],
    "properties": [
      {
        "name": "IsOn",
        "type": "boolean",
        "remark": "light switched on",
        "declaration": "2",
        "derived": true,
        "parameter": false,
        "tags": [
          "linkable"
        ],
        "isStatic": false
      },
      ...
    ],
    "fullName": "SmartCOM.Light.Light",
    "displayName": "Light",
    "autoStart": false
  }
}

Next, a POST request is sent to "http://[Smart_Building_Automation_IP]/api/instances/SC1_M04.Light1/SwitchOn" with the following parameters in the header:

  • instanceId: SC1_M04.Light1
  • action: SwitchOn
  • body: [ ]

This calls the specified method and switches the light on. The current status can be checked by sending a GET request to "http://[Smart_Building_Automation_IP]/api/instances/SC1_M04.Light1/IsOn". The response contains the current status, in this case "true".

{
  "statusCode": 200,
  "statusText": "success",
  "data": true
}