HTTP API

Introduction

Every hardware device has an serialno in the form F:S (e.g. 12:34). The F part of serialno is the product family and it is common within similar hardware. For example, all DinSwitch devices have serialnos in the form 12:S, whereas all Plugs have 14:S and and so on. S is an incremental number unique for every device within the same family. The serialno of a device is the identifier used by the server, the UI and the API endpoints. Example serialnos are: 12:4, 12:7, 14:20, 8:4

For every device, two random keys are generated. One is device_key and it is the setup Access Point (AP) WPA password and it is also used to claim a device. The second key is a long sequence that the server uses to authenticate a device connection and the device uses to authenticate the server.

All communications and interactions with devices are made through the server by default. There is the option to send HTTP requests with device commands directly to devices on their IP address once they are connected on a LAN, but it is disabled by default for security reasons. The server authenticates the devices, authenticates the clients and passes commands and data between the two. The server handles datalogging and rule evaluation among other things.

Authentication

Logged-in user is determined by the server, using a supplied api_key or an access_token via COOKIE, POST or GET parameters. In case, access_token or api_key are supplied multiple times, api_key has precedence over access_token and then, GET parameters have the highest priority, POST parameters are next and last are COOKIE

An access token is generated in OAuth2 fashion when a user logs-in using his email and password. Multiple access_tokens can be active up to a certain limit. When this limit is exceeded, the older access_tokens are replaced and invalidated. Access tokens also have an expiration date. This means that access tokens are temporary

An api_key on the other hand, never expires but every user account is limited to only one. You can generate an api_key, (which will replace the already existing one) by visiting the user account section in the HAM website and using the option generate API key

/get_user_devices.php

URL: https://api.hamsystems.eu/get_user_devices.php

Returns user device information including floorplans, groups and allowances

Parameters: [GET/POST]

• access_token or api_key

Response:

/device_command.php

URL: https://api.hamsystems.eu/device_command.php

Parameters [GET/POST]

• "access_token or api_key" - for authentication

• "serialno" of the device

• "command" - the command to send to the device

Responses:

example for "serialno = 12:0, command = READ"