REST API V1 Reference

Overview

This document describes the REST API and provided by Isotel IoT software. Web server provides the following functionality:

  • Application information

  • Active device access

  • Record access

  • Activity log access

  • Properties access

  • Credentials management

  • Remote access through Skype API

Structure of REST URIs

IoT REST API provide access to resources via URI paths. To use a REST API, client application makes an HTTP request and parse the response. The default response format is JSON, though for many resources client can specify plain text format as well. Methods used are standard HTTP methods like GET, POST and DELETE.

URIs for the REST API resource have the following structure:

Local resources:

/api/v1/me/{resource}
/api/v1/terminal/{resource}
/api/v1/credentials/{resource}
/api/v1/manager/{resource}

Response format

Response format is JSON by default, otherwise defined by URI suffix:

Suffix

MIME Type

Description

None

application/json

JSON format, default

.json

application/json

JSON format, default

.txt

text/plain

Plain text format

.html

text/html

HTML format (where applicable only)

Response format for successful 200 response varies and is specified for each resource. For other response codes, json format is:

{"message" : "Error response message"}

General

/api/v1/me

List of devices, both active and inactive

Required permission - device_list

Parameter

Value

Description

Methods

active

boolean

Returns only active devices if set to true

GET

Example request URI(s):

  • /api/v1/me

  • /api/v1/me?active=true

GET

Returns List of devices

Fields:

  • “name”: device full name

  • “active”: true if device is currently connected and running

  • “root”: short unique designation (only active devices, can change on reconnect)

  • “port”: physical connection port (only active devices)

200 Response format example

[
 {"name":"Isotel myLab Thermometer V1.1.08 5478AA2C00000102","root":"device0","status":"active","port":"1CED:4001:64010210161A0674"},
 {"name":"PlutonPower DCCT Control System","status":"inactive"},
 {"name":"EC-16-20AHR-L2A-1.2.0-1901 50446110 (00043E29B547)","status":"inactive"}
]

/api/v1/me/version

Application info containing IoT version, build number and REST API version

Required permission - server_info

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/version

GET

Returns version information

200 Response format example

{
 "application": "ISOTEL Data-acquisition & Metering Smart Gateway Pro",
 "major": "1",
 "minor": "0",
 "release": "180827-1",
 "build": "882",
 "api": "1.0.844",
 "status": "OK",
 "mode": "premium"
}

/api/v1/me/servertime

Current server time

Required permission - server_info

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/servertime

GET

Returns current server time

200 Response format example

{
    "time":"1460639372.176",
    "status":"OK"
}

/api/v1/me/arptable

Arp table mapped to users accessing the system

Used to obtain mac address from the IP address, and to be able for a service to identify the user logged in from the request.

Status for users can be:

  • inactive: user hasn’t accessed API, his HW address not found in arp

  • present: user hasn’t accessed API, but his HW address is present in arp

  • active: user has accessed API, either in local network or from outside

Required permission - arp_info

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/arptable

GET

Returns current arp table entries

200 Response format example

[
 {
   "ip": "192.168.1.105",
   "mac": "84-be-52-85-50-8d",
   "username": "guest_6775657374",
   "status": "active",
   "time": "1498153566.75"
 },
 {
   "ip": "127.0.0.1",
   "mac": null,
   "username": "admin@isotel.eu",
   "status": "active",
   "time": "1498153614.877"
 },
 {
   "ip": "192.168.1.105",
   "mac": "84-be-52-85-50-8d",
   "username": "ktine@isotel.eu",
   "status": "active",
   "time": "1498153617.028"
 }
]

/api/v1/me/activity

Server activity log

Required permission - activity_log

Parameter

Value

Description

Methods

limit

integer

limit the number of results

GET

from

‘first’, ‘start’, timestamp

lower limit timestamp for log access

GET, DELETE

to

‘last’, ‘end’, timestamp

upper limit timestamp for log access

GET, DELETE

module

string

module filter

GET

severity

string

severity filter

GET

title

string

title filter

GET

status

string

status filter

GET

  • from=start, from=first: both mean that the lower limit is the first log record

  • to=end, to=last: both mean that the upper limit is the last log record

  • title=_: Means wildcard, title is not-null

  • status=_: Means wildcard, status is not-null

Example request URI(s):

  • /api/v1/me/activity?from=start&limit=100

  • /api/v1/me/activity?to=1460639372.176&severity=WARNING&module=RecordStore

GET

Returns activity log

200 Response format example

[
   {"last":"1460633274.42","module":"Service TCP Server","severity":"INFO","message":"Service TCP Server starting on port 9003"},
   {"last":"1460633274.538","module":"Server Manager","severity":"INFO","message":"HTTP server starting on port 9001"},
   {"last":"1460633275.489","module":"Serial Utility","severity":"INFO","message":"Searching available serial ports... "},
   {"last":"1460633275.493","module":"Bluetooth Util","severity":"INFO","message":"Searching available bluetooth devices... "},
   {"last":"1460640258.914","first":"1460640193.218","N":3,"module":"HTTP Server","severity":"API","message":"Request: GET me/activity, IP 127.0.0.1, size 0 B, duration < 100 ms"}
]

POST

Push new notification message to log

Request format example

{
       "last": "1477066857.626",
       "module": "MonitorService",
       "severity": "INFO",
       "message": "Electricity cut",
       "status": "Open",
       "title": "No Electricity --2"
}

200 Response format example

{
 "status":"OK",
}

400 Response

  • Returned when request body doesn’t contain valid data

401 Response

  • Returned when client is not authorized to modify activity log

DELETE

Deletes log messages from database according to ‘from’ and ‘to’ parameter constraints

200 Response format example

{
   "message":"Deleted 532 log entries."
}

401 Response

  • Returned when user doesn’t have permission to modify log database

400 Response

  • Returned if invalid method is used

Connectivity

/api/v1/me/connections{adapter}

Get a list of all currently running connections.

List includes all connected adapters

  • Serial

  • USB

  • Bluetooth

  • UDP client

  • UDP server session

Required permission - port_info

Parameter

Value

Description

Methods

Protocol Levels:

Level

Description

Settings

physical, phy

low level communication

ascii (bool)

frame

frame layer

reset (bool)

transport, trans

optional intermediate layer

custom

custom protocol implementation

reset (bool)

message, msg

message layer

reset (bool), retry_count (int), timeout (int)

Example request URI(s):

  • /api/v1/me/connections

  • /api/v1/me/connections/usb

  • /api/v1/me/connections/1CED:4001:64010210161A0674

GET

Returns connection list

200 Response format example

{
 "connections": [
   {
     "port": "COM6",
     "status": "Rx: 4424 B, Rx Errors: 0, Tx: 32, Tx Errors: 0",
     "preset": "board",
     "state": "Connected"
   },

   {
     ""port": "127.0.0.1:52818",
     "status": "Rx: 1068, Rx Errors: 0, Tx: 32, Tx Errors: 0",
     "preset": "udp",
     "state": "Connected"
   }

 ],
 "time": "1496146558.123"
}

Connection details

{
 "1CED:4001:64010210161A0674": {
   "status": {
     "layer": "PHYSICAL",
     "id": "1CED:4001:64010210161A0674",
     "rx": 554725,
     "tx": 150,
     "rx_error": 0,
     "tx_error": 0,
     "preset": null,
     "time": "1518719967.035"
   },
   "Message": {
     "status": {
       "layer": "MESSAGE",
       "id": "Message",
       "rx": 77,
       "tx": 66,
       "rx_error": 0,
       "tx_error": 0,
       "rx_discard": 0,
       "tx_discard": 0,
       "tx_retry": 0,
       "devices": {
         "Dewelab Ins-1.0a1 v1.2.0.2 1000200000002 807060504030201 0 FFFFFFFFFFFFFFA1": {
           "name": "Dewelab Ins-1.0a1 v1.2.0.2 1000200000002 807060504030201 0 FFFFFFFFFFFFFFA1",
           "loaded_messages": 84,
           "pending_requests": 0,
           "recording": true,
           "msg_layer": "Message.msg",
           "port": "1CED:4001:64010210161A0674",
           "state": "active",
           "time": "1518719967.035"
         }
       }
     }
   },
   "LongTransport": {
     "1": {
       "NOP": {
         "status": {
           "layer": "CUSTOM",
           "id": "NOP",
           "rx": 9169,
           "tx": 0,
           "rx_error": 0,
           "tx_error": 0
         },
         "Stream.0.1": {
           "status": {
             "layer": "CUSTOM",
             "id": "Stream.0.1",
             "rx": 9169,
             "tx": 0,
             "rx_error": 0,
             "tx_error": 0,
             "port": "9100",
             "adapter": "Stream.0.1",
             "channel": 0,
             "protocol": 1
           }
         }
       }
     },
     "status": {
       "layer": "TRANSPORT",
       "id": "LongTransport",
       "rx": 9169,
       "tx": 0,
       "rx_error": 0,
       "tx_error": 0
     }
   }
 }
}

/api/v1/me/serial/{adapter}/{level}

List of available serial ports with their current status, and connected adapter info and settings

Required permission - port_info

Parameter

Value

Description

Methods

after

‘now’, timestamp

force port re-scan if last scan predates given time

GET

  • after=now: means parameter specifies current server time which will trigger an immediate request (query) to the device to send latest update.

Protocol Levels:

Level

Description

Settings

physical, phy

low level communication

ascii (bool)

frame

frame layer

reset (bool)

transport, trans

optional intermediate layer

custom

custom protocol implementation

reset (bool)

message, msg

message layer

reset (bool), retry_count (int), timeout (int)

Example request URI(s):

  • /api/v1/me/serial?after=now

  • /api/v1/me/serial/home_preset

  • /api/v1/me/serial/home_preset/message

GET

Returns list of ports with their connection status. Re-scan can be forced by specifying ‘after’ parameter

200 Response format example

{
   "ports": [
       {"port":"COM4","connected":false},
       {"port":"COM6","connected":false},
       {"port":"COM31","connected":"mylab3"},
       {"port":"COM32","connected":false}
   ],
   "time":"1460633312.968"
}

Getting adapter protocol stack status result:

200 Response format example

{
 "phy": {
   "adapter": "COM31",
   "type": "UART",
   "rx": 2044,
   "tx": 172
 },
 "frame": [
   {
     "rx": 94,
     "tx": 43,
     "rx_error": 0,
     "tx_error": 0
   }
 ],
 "msg": [
   {
     "rx": 94,
     "tx": 43,
     "rx_discard": 0,
     "tx_discard": 0,
     "tx_error": 0,
     "tx_retry": 0,
     "pending_count": 0,
     "msg_timeout": 1500,
     "max_retry_count": 10
   }
 ],
 "time": "1468319412,29"
}

404 Response

  • Returned when specified adapter/connection is not found

POST

Updates the specified protocol setting

Request format example

{'timeout': 2000}

200 Response format example

{'result': 'OK'}

422 Response

  • Returned when unable to complete setting request

401 Response

  • Returned when client is not authorized to modify settings

/api/v1/me/bluetooth/{adapter}/{level}

List of available Bluetooth adapters, and connected adapter info and settings

Required permission - port_info

Parameter

Value

Description

Methods

after

‘now’, timestamp

force adapter re-scan if last scan predates given time

GET

  • after=now: means parameter specifies current server time

Example request URI(s):

  • /api/v1/me/bluetooth?after=now

GET

Returns list of ports with their connection status. Re-scan can be forced by specifying ‘after’ parameter

200 Response format example

{
   "devices":[
        {"name":"HTC EVO 3D X515m","address":"1CB094608000","connected":false},
        {"name":"Energy Control Link","address":"00043E29B000","connected":false},
        {"name":"Energy Control Link","address":"00043E29B001","connected":false}
    ],
    "time":"1460643134.167"
}

Device Access

/api/v1/me/{device_name}/{substructure}/…/{variable}

Device contents. Includes both active devices and record data stored on permanent storage.

Functionality:

  • Gather variable data (specified by structure/variable name)

  • Gather raw arguement data (specified by message number)

  • Set variable values

  • Set raw message arguments

  • Send varaible queries

  • Perform basic scale, interpolation and aggregation calculations over record data

  • {device_name} is either full device title, for example ‘myLab Thermometer V1.1.08 5478AA2C00000102’ (spaces can be replaced by ‘_’ if convenient), or ‘deviceX’ runtime designation for active devices

  • {substructure} refers to device structure, which can contain variables or other substructures

  • {variable} refers to a textual or numeric variable

Required permission - device_access

Parameter

Value

Description

Methods

unit

boolean

include variable unit in output

GET

accuracy

boolean

include variable accuracy in output

GET

options

boolean

include enumeration value list in output

GET

attributes

string

include given protocol attribute in output

GET

timeout

integer

active device request timeout [ms]

GET

active

boolean

include only active device data

GET

after

‘now’, timestamp

force data refresh if last update predates ‘after’

GET

advanced

boolean

advanced section filter

GET

development

boolean

development section filter

GET

hidden

boolean

hidden section filter

GET

limit

integer

limit the number of record results (record)

GET

from

‘first’, ‘start’, timestamp

lower limit timestamp for record access (record)

GET

to

‘last’, ‘end’, timestamp

upper limit timestamp for record access (record)

GET

scale

integer

number of elements in scale calculation (record)

GET

average

timestamp

average interval duration (record)

GET

interpolate

integer

define interpolation level (0 or 1)

GET

calc

string

aggregate function (record)

GET

  • from=start, from=first: both mean that the lower limit is the first record

  • to=end, to=last: both mean that the upper limit is the last record

Active device access

Example request URI(s):

  • /api/v1/me/device0?advanced=true&hidden=true

  • /api/v1/me/device0/1

  • /api/v1/me/myLab_Thermometer_V1.1.08_5478AA2C00000102/Measure?active=true

  • /api/v1/me/myLab_Thermometer_V1.1.08_5478AA2C00000102/Measure/T?unit=true&after=now

  • /api/v1/me/myLab_Thermometer_V1.1.08_5478AA2C00000102.html?advanced=true&after=now

GET variable data

Returns current values for given device/substructure/parameter

200 Response format example

{
    "status":"OK",
    "Measure":{
        "T":{"value":"-242.59","unit":"oC"},
        "Tmin":{"value":"-244.34","unit":"oC"},
        "Tmax":{"value":"-232.58","unit":"oC"},
        "Tint":{"value":"-14433140.36","unit":"oC"},
        "Alarmed_cnt":{"value":"1"},
        "Cleared_cnt":{"value":"0"}
    },
    "time":"1460652285.215"
 }

GET raw arguemtn data

Returns raw arguments for given message number

200 Response format example

{"time":"1500287778.524","N":1,"len":7,"args":"00000039B30100"}

422 Response

  • Returned when ‘after’ or ‘active’ parameters are set and the specified device is not active, or device does not exist

POST variable data

Attempts to set valued of given parameter or whole structure. Note that in a typical device, not all variables are settable, some are read-only. Client also need to ensure that provided data is in valid data type and range.

Request format example

{
 "Alarmed_cnt": {"value": "4"}
}

200 Response format example

{
 "status":"Ack",
 "Alarmed_cnt":{"value":"4"},
 "time":"1460653621.707"
}

400 Response

  • Returned when request body doesn’t contain valid data

401 Response

  • Returned when client is not authorized to modify device data

POST raw argument data

Sends raw argument data for given message

Request format example

{"args":"00000039B30100"}

200 Response format example

{
 "status":"OK",
 "time":"1460653621.707"
}

POST variable query

Sends message queries for given parameters, asking device to update newest arguments. This is done by sending an empty query to given parameter

Request format example

{}

200 Response format example

{
 "status":"OK",
 "time":"1460653621.707"
}

Record access

Record access is triggered in two cases:

  • Device specified in the request is not active, but has records stored. In this case, the newest newest record is returned

  • Request contains any record specific parameters (limit, from, to, scale, average)

Regular Mode

In regular mode, the samples returned will are defined by ‘from’, ‘to’ and ‘limit’ parameters.

Default limit is 100.

If only ‘from’ timestamp is defined, the first n=limit samples from that timestamp will be returned.

If ‘to’ timestamp is defined, the last n=limit samples to that timestamp will be returned.

Scale Mode

Instead of taking the first or last <limit> samples, in scale mode samples are calculated in N equidistant points (N-1 intervals)

t_i = (i / N) (to_time - from_time) + from_time

Scale interval durations is calculated as:

dt = (to - from)/(N - 1)

As defined above, scale calculation is accessed by specifying the scale=<N> parameter in HTTP request

Resulting json entry consists of:

  • time - timestamp for the given interval

  • value - parameter value at given timestamp

  • M - number of records between previous and current interval

Scale and limit parameters are mutually exclusive, specifying both in the same request will result in error.

If no records are available at given interval, the latest value previous to interval timestamp will be returned. Thus, multiple sample may share the same value

It is possible that a value might be undefined (?), if its dependent cross references are not defined at a given interval.

Average Mode

Average mode works in conjunction with scale mode, by calculating average value of parameter on a given interval (length of interval defined by ‘average’ parameter).

Resulting json format is the same as with scale mode, with added parameter:

  • SD - standard deviation of values in each interval

Interpolation Mode

Interpolation mode works in conjunction with scale mode, it calcualates the scale sample value by performing linear interpolation on closest samples.

Final sample value is y = y0 + k dt, where dt is time from the last t0, and k is (y1-y0)/(t1-t0), for a set (y1, t1).

parameter values:

interpolate=0 - no interpolation, same as ordinary scale mode itnerpolate=1 - linear interpolation as described above

Example request URI(s):

  • /api/v1/me/device0?limit=10&from=start

  • /api/v1/me/myLab_Thermometer_V1.1.08_5478AA2C00000102/Measure?scale=10&from=

  • /api/v1/me/myLab_Thermometer_V1.1.08_5478AA2C00000102/Measure/T?unit=true&after=now

  • /api/v1/me/My%20Counter%20V1.0%20(udp)/myCounter/value?from=1499347981&to=end&scale=20&interpolate=1

GET

Calculates and returns records according to parameters. Default limit is 100 samples.

200 Response format example

[
   {"time":"1460654235.202","N":1,"T":{"value":"25.37"}},
   {"time":"1460654237.203","N":2,"T":{"value":"25.38"}},
   {"time":"1460654239.202","N":1,"T":{"value":"25.37"}},
   {"time":"1460654241.202","N":1,"T":{"value":"25.60"}},
   {"time":"1460654243.202","N":1,"T":{"value":"25.65"}}
]

400 Response

  • Returned when parameters are missing or in conflict, such as limit and scale parameter being defined simultaneously, or average parameter missing the scale parameter

/api/v1/me/{device_name}/device_status

Device layer status and settings

Required permission - device_access

Parameter

Value

Description

Methods

Settings:

Level

Description

format

clear_pending

clear pending message requests

boolean

recording

turn record store on/off

boolean

Example request URI(s):

  • /api/v1/me/device1/device_status

GET

200 Response format example

{
 "name": "Dewelab Ins-1.0a1 v1.2.0.2 1000200000002 807060504030201 0 FFFFFFFFFFFFFFA1",
 "loaded_messages": 84,
 "pending_requests": 0,
 "recording": true,
 "msg_layer": "Message.msg",
 "port": "1CED:4001:64010210161A0674",
 "state": "active",
 "time": "1518638525.693",
 "root": "device0"
}

Get device status report

POST

Updates device setting

Request format example

{'recording': false}

200 Response format example

{'result': 'OK'}

422 Response

  • Returned when unable to complete setting request

401 Response

  • Returned when client is not authorized to modify settings

Properties

/api/v1/me/{identifier}/properties/{property_name}/{substructure}/…

Device may be given some extra data from the client side, where IoT may store this data in corresponding database structure. Properties can also be assigned under arbitrary identifiers, thus not belonging to any particular device. The data is thus given some URI and whole or partial json data.

Properties also support addressing structures/subdocuments, similar to device structures.

  • {identifier} identifier, can be a device or arbitrary

  • {property_name} property name

  • {substructure} property substructure(s), optional

Required permission - property_access

Parameter

Value

Description

Methods

limit

integer

limit the number of returned list property entries

GET, DELETE

from

‘first’, ‘start’, integer

lower limit index for list property access

GET, DELETE

to

‘last’, ‘end’, integer

upper limit index for list property access

GET, DELETE

filter

string

filter group link entries

GET

filterout

string

fitler out group link entries

GET

{parameter}

{operator}-{value}

arbitrary parameter for list element checking

GET, DELETE

Example request URI(s):

  • /api/v1/me/device1/properties/pstruct

  • /api/v1/me/device1/properties/pstruct/str1/str2

GET

Returns the value of given property or substructure

200 Response format example

{
  "pstruct": {
     "data": {
        "str1" : {
            "str2" : {
                "val1" : 5,
                "val2" : 45
             }
         }
      },
      "time" : "1460721752.992"
   }
}

404 Response

  • Returned when property is not found

500 Response

  • Returned on general database error

POST

Sets or overwrites given property or substructure

Request format example

{
    "str2" : {
        "val1" : 5,
        "val2" : 45
    }
}

200 Response format example

{"result":"OK"}

401 Response

  • Returned when client is not authorized to change properties

422 Response

  • Returned when database system in unable to complete operation

DELETE

removes the given property or substructure

200 Response format example

{"result":"OK"}

401 Response

  • Returned when client is not authorized to change properties

422 Response

  • Returned when database system in unable to complete operation

Services

/api/v1/me/services/{service_name}

Service API enables using external applications/scripts with IoT

Service connects to IoT through TCP connection, if Service TCP server is enabled in IoT.

Required permission - service_access

Parameter

Value

Description

Methods

action

string

defines action keword to be sent to service

GET

Example request URI(s):

  • /api/v1/me/services/service0?action=STOP

GET

Send notification and wait for reply from service

200 Response format example

{"status":"Stop confirmed"}

404 Response

  • Returned when service is not found

422 Response

  • Returned when unable to communicate with service/complete request

POST

Send data or notification and wait for reply from service

Request format example

{ "action" : "STOP" }

200 Response format example

{"status":"Stop confirmed"}

404 Response

  • Returned when service is not found

422 Response

  • Returned when unable to communicate with service/complete request

/api/v1/me/services/pin/{service_name}

Generate PIN number used for connecting service to IoT

IoT checks credentials and generates PIN number if properly authorized

Required permission - service_access

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/services/pin/TestService

GET

Get PIN number used for connecting service to IoT

200 Response format example

{"name":"TestService", "pin":123456}

401 Response

  • Returned when client is not authorized to execute given service

Terminal Remote Commands

/api/v1/terminal/commands

Command interface enables user to perform various tasks, such as sending custom data to devices, managing connections, settings, etc.

Required permission - command_access

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/terminal/commands

POST

Executes command

Request format example

{
    "command": "openSerialPort",
    "parameters": [
         "mylab3"
    ]
}

200 Response format example

{"result": "OK"}

401 Response

  • Returned when client is not authorized to execute commands

Command Reference

File and data management Commands:

  • sendFile(file) Send file

  • sendFile(file, regex) Send file with stop condition given in regex format

  • cd() Show current directory

  • dir() List current directory contents

  • wait(timeout) Wait for some time given in seconds

  • hex2bin( AA BB 88 ) Convert data from hex string to binary and send it to serial driver

  • sendData(entry, regex, timeout) Send text to serial driver and wait response condition given in regex format

Connection management:

  • openSerialPort(preset/port) Open serial port by given configuration

  • closeSerialPort(preset/port) Close serial connection

  • openBluetoothConnection(preset/address) Open serial port by given configuration

  • closeBluetoothConnection(preset/port) Close bluetooth connection

  • openUDPConnection(host, port, preset) Open UDP client connection

  • closeUDPConnection((host, port)/preset) Close UDP client connection

  • openUSBConnection(deviceID, preset) Open USB connection

  • closeConnection(connectionID) Close phy connection (any type)

  • setAutoConnect(type, id, true/false) Enable/disable autoconnect for given device id (type - usb/uart/bluetooth…)

Alias management and running applications:

  • setAlias(entry, command) Add new alias

  • setAlias(entry, command, description) Add/set alias with given description shown in run menu

  • clearAliasList() Clear all alias entries

  • run(application) Run external application connect it with terminal via stdin/stdout, stderr is reported to activity log

  • run(application, label) Run application with optional label

  • kill() Kill running application

Other:

  • help() Display help

  • alarm(timeout, message) Send delayed alarm message to process/TCP client, if no other output is sent in the meantime. Timeout in (ms)

  • timeout() Show timeout for variable access in (ms)

  • timeout(new_timeout) Set new timeout for variable access in (ms)

  • exit(code) Exit application with given code

/api/v1/terminal/aliases

Commands can be grouped together under an alias and executed in a sequence

Required permission - command_access

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/terminal/aliases

POST

Executes alias commands

Request format example

{
  "alias": "test4",
  "phy": "mylab3"
}

200 Response format example

{"result": "OK"}

401 Response

  • Returned when client is not authorized to execute commands

/api/v1/terminal/config

Here IoT settings can be accessed and changed

Required permission - server_configuration

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/me/terminal/config

GET

Get current application configuration file content in json form

200 Response format example

See Configuration example under Configuration Interface.

POST

Overrides server configuration. Settings take effect depending on context, usually when the relevant component is restarted

Request format example

See Configuration example under Configuration Interface.

200 Response format example

{"result": "OK"}

401 Response

  • Returned when client is not authorized to change configuration

User and Group Access Permisions

/api/v1/credentials

Credentials used for accessing this request

Credentials consists of user information (public key, principal information), individual resource permission levels and group membership

Resource categories:

  • server_info - version and time info

  • port_info - serial and bluetooth ports

  • activity_log - server activity log

  • device_list - list of active and inactive devices

  • device_access - access to device data, can be defined for each device separately

  • property_access - access to property data, can be defined for each property separately

  • service_access - access to services, can be defined for each service separately

  • command_access - server command interface

  • user_management - user credentials management

  • user_registration - register new user/ sign certificate

  • server_configuration - server configuration settings

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/credentials

GET

Returns user credentials

User credentials entries use either username or public key as identifier.

  • For Basic AUTH mode, it is represented by the usename

  • For 2-way SSL mode, it is represented as hex string of the public certificate key in its primary encoding format (usually X.509).

200 Response format example

{
 "key":"30820122300D06092A864886F70D01010105000382010F003082010A0282010100C7E0A3BD9FA519446F2044E0E6
   F07573E0706BA576623C6F0C9A1783286F63310BE3F2617D1833D2B525DD92CA39CFA14A08BA09DCC134F705908916C43D79
   A554921D006C16EEAAD1AEDC66E1E71E3A15E2D5E0365ED11A8EE0B843282EEC9A56505949C31BBFBA7F662F94D580652047
   05536A0FC59FBBEDE9F13CCC1F7DA62CB7FB7176C4A4EC04D2657C38BEC771307BFBA54E5A7CAF0CF1973F42682AD995E9BA
   285E9112C6F9D88DF840656D75A7DB6A02B882028737F225E406179FBF6E4FC32E7FFF2A46FB0DC997661584BDCF8AFC8EA8
   07581D79A434D1C06832A0EC01F7A47D49FE211EADEDCB4F4BF65B3F26808AE76A7F79D496D73C2F8ACF530203010001",

 "principal":"CN=IoT test client,OU=IoT,O=Isotel,L=Ljubljana,ST=Ljubljana,C=SI",

 "permissions":[],
 "groups":[
     {
       "name":"admin",
       "key":null
     }
 ]
}

/api/v1/credentials/users

User information and management

Required permission - user_management

Parameter

Value

Description

Methods

key

string

username/public key

GET, DELETE

filter

string

name/principal filter

GET, DELETE

type

string

user type (username, certificate)

GET, DELETE

Relevant JSON fields:

Field

Description

key

user public key

username

username id

password

password (new user entry only)

registered

true if user is valid and registered

active

true if user credentials are enabled

last_modified

UTC timestamp for last modification

principal

user principal information (name, org,…)

groups

group membership list

permissions

resource permission list

sub_permissions

sub-resournce permission list

resource

resource name

read

resource read permission (bool)

write

resource write permission (bool)

Example request URI(s):

  • /api/v1/credentials/users?filter=Isotel

GET

Returns user credentials in array form, according to given filter parameters. User principal information is checked if it contains “filter” parameter string If “key” is specified, it first searches for matching public key

The example below returns both Basic Auth and certificate users

200 Response format example

[
 {
   "key":    "30820122300D06092A864886F70D01010105000382010F003082010A0282010100B6C71B1131A575398BFDFFE865DA62EE3322E96584178F1784FBB95D6308ACBCF
   E621FCF23AA5AF526347A3406165F5E478DC9B59D8EA932BD664D2865295AF98B11884F38E7B94A833A043751B23776D4A5CA4B52290FC11BEB4A4
   A3E681A98067ACDBC9E483C7594F01C7969A0C7A009E4963A717977279E9E9AD99977C838B87B6F6994EDAA9ABA6085C59D9B2257A660A99E214A647905FEAA3148D2
   9B20B2C92F3269C1F2BC2F12E70AC01D93A902EAE8220100A9DAD898AB818ED8583A70F51FF8382ECE3104B6F5BE29ACA8624008185DA0E5571 5AEF10DE9846397C70
   88F219E435873D148C27F71277A15369705788798D654CE9A712806D387D0390203010001",

   "principal": "CN=Tine K,OU=IoT,O=Isotel,L=Ljubljana,ST=Lj,C=SI",
   "permissions": [
     {
       "resource": "device_access",
       "read": false,
       "write": false,
       "sub_permissions": [
         {
           "resource": "myLab Thermometer V1.1.08 1",
           "read": true,
           "write": true
         },
         {
           "resource": "DCCT Control System ",
           "read": true,
           "write": true
         }
       ]
     },
     {
       "resource": "command_access",
       "read": true,
       "write": true
     }
   ],
   "groups": [
     {
       "name": "guest",
       "key": null
     }
   ]
 },
 {
   "key":   "30820122300D06092A864886F70D01010105000382010F003082010A0282010100C7E0A3BD9FA519446F2044E0E6F07573E0706BA576623C6F0C9
   A1783286F63310BE3F2617D1833D2B525DD92CA39CFA14A08BA09DCC134F705908916C43D79A554921D006C16EEAAD1AEDC66E1E71E3A15E2D5E0365ED11A8EE0B8
   43282EEC9A56505949C31BBFBA7F662F94D58065204705536A0FC59FBBEDE9F13CCC1F7DA62CB7FB7176C4A4EC04D2657C38BEC771307BFBA54E5A7CAF0CF1973F4
   2682AD995E9BA285E9112C6F9D88DF840656D75A7DB6A02B882028737F225E406179FBF6E4FC32E7FFF2A46FB0DC997661584BDCF8AFC8EA807581D79A434D1C068
   32A0EC01F7A47D49FE211EADEDCB4F4BF65B3F26808AE76A7F79D496D73C2F8ACF530203010001",

   "principal": "CN=IoT derived client cert,OU=IoT,O=Isotel,L=Lj,ST=Lj,C=SI",
   "permissions": [],
   "groups": [
     {
       "name": "admin",
       "key": null
     }
   ]
 },
 {
   "username": "admin@isotel.eu",
   "principal": "administrator",
   "registered": true,
   "active": true,
   "last_modified": 1484568256,
   "permissions": [],
   "groups": [
     {
       "name": "admin",
       "key": null
     }
   ]
 },
 {
   "username": "user@isotel.eu",
   "principal": "test user",
   "registered": true,
   "active": true,
   "last_modified": 1484568256,
   "permissions": [
     {
       "resource": "device_access",
       "read": true,
       "write": true
     }
   ],
   "groups": []
 }
]

POST

Adds or updates given user credentials. Format is the same as returned from GET request

Request format example

{
  "key": "30820122300D06092A864886F70D01010105000382010F003082010A0282010100B6C71B1131A575398BFDFFE865DA62EE3322E96584178F1784FBB9
  5D6308ACBCFE621FCF23AA5AF526347A3406165F5E478DC9B59D8EA932BD664D2865295AF98B11884F38E7B94A833A043751B23776D4A5CA4B52290FC11BEB4A4A3E
  681A98067ACDBC9E483C7594F01C7969A0C7A009E4963A717977279E9E9AD99977C838B87B6F6994EDAA9ABA6085C59D9B2257A660A99E214A647905FEAA3148D29B
  20B2C92F3269C1F2BC2F12E70AC01D93A902EAE8220100A9DAD898AB818ED8583A70F51FF8382ECE3104B6F5BE29ACA8624008185DA0E55715AEF10DE9846397C708
  8F219E435873D148C27F71277A15369705788798D654CE9A712806D387D0390203010001",

  "principal": "CN=Tine K,OU=IoT,O=Isotel,L=Ljubljana,ST=Lj,C=SI",
  "permissions": [
    {
      "resource": "device_access",
      "read": false,
      "write": false,
      "sub_permissions": [
        {
          "resource": "myLab Thermometer V1.1.08 1",
          "read": true,
          "write": true
        }
      ]
    },
    {
      "resource": "command_access",
      "read": true,
      "write": true
    }
  ],
  "groups": [
    {
      "name": "testGroup",
      "key": null
    }
  ]
}

200 Response format example

{"result": "OK"}

DELETE

Deletes user according to given filters. If multiple users match the criteria, only first user is deleted to prevent accidental deletion

200 Response format example

{"result": "OK"}

/api/v1/credentials/users/pin

Generating and managing PIN system pending users

Required permission - user_management

Parameter

Value

Description

Methods

pin

int

user PIN

GET, DELETE

filter

string

user principal filter

GET, DELETE

Relevant JSON fields:

Field

Description

pin

user PIN number

description

user description/name

groups

group membership list

permissions

resource permission list

sub_permissions

sub-resournce permission list

resource

resource name

read

resource read permission (bool)

write

resource write permission (bool)

Example request URI(s):

  • /api/v1/credentials/users/pin?pin=123456

GET

Returns pending user credentials in array form, according to given filter and pin parameters. User principal information is checked if it contains “filter” parameter string If “pin” is specified, it first searches for matching PIN

200 Response format example

[
 {
   "pin": 123456,
   "description": "User name xyz",
   "permissions": [
     {
       "resource": "device_access",
       "read": false,
       "write": false,
       "sub_permissions": [
         {
           "resource": "myLab Thermometer V1.1.08 1",
           "read": true,
           "write": true
         },
         {
           "resource": "DCCT Control System",
           "read": true,
           "write": true
         }
       ]
     },
     {
       "resource": "command_access",
       "read": true,
       "write": true
     }
   ],
   "groups": [
     {
       "name": "guest",
       "key": null
     }
   ]
 }

]

POST

Adds or updates given pending user credentials. Format is the same as returned from GET request

Request format example

{
  "description": "User name xyz",


  "permissions": [
    {
      "resource": "device_access",
      "read": false,
      "write": false,
      "sub_permissions": [
        {
          "resource": "myLab Thermometer V1.1.08 1",
          "read": true,
          "write": true
        }
      ]
    },
    {
      "resource": "command_access",
      "read": true,
      "write": true
    }
  ],
  "groups": [
    {
      "name": "testGroup",
      "key": null
    }
  ]
}

200 Response format example

{"result": "OK"}

DELETE

Deletes user according to given filters. If multiple users match the criteria, only first user is deleted to prevent accidental deletion

200 Response format example

{"result": "OK"}

/api/v1/credentials/users/register

User registration using PIN system

PIN must be provided either as url encoded parameter or in json body. If it matches a pending user in database, corresponding permissions are assigned to provided username (basic auth) or certificate (2-way ssl)

Required permission - user_management

Parameter

Value

Description

Methods

pin

string

user key

GET, POST

Example request URI(s):

  • /api/v1/credentials/users/register?pin=123456

GET

Register user with provided PIN and certificate

200 Response format example

{"result": "OK"}

400 Response

  • Returned when PIN is not specified correctly

422 Response

  • Returned when there is no matching pending user in database to register

POST

Register user with provided PIN and certificate

Request format example

{"pin":123456 }

200 Response format example

{"result": "OK"}

400 Response

  • Returned when PIN is not specified correctly

422 Response

  • Returned when there is no matching pending user in database to register

/api/v1/credentials/groups

Group information and management

Required permission - user_management

Parameter

Value

Description

Methods

key

string

group key

GET, DELETE

filter

string

group name filter

GET, DELETE

Relevant JSON fields:

Field

Description

key

user public key

name

group name

description

group description

use_credentials_key

use certificate public key for group key id if true

permissions

resource permission list

sub_permissions

sub-resournce permission list

resource

resource name

read

resource read permission (bool)

write

resource write permission (bool)

Example request URI(s):

  • /api/v1/credentials/groups

GET

Returns group credentials in array form, according to given filter parameters. Group name is checked for “filter” parameter string If “key” is specified, it first searches for group key if it exists

200 Response format example

[
 {
   "name": "admin",
   "key": null,
   "description": "Administrator group, has full access to all resources, including user management",
   "permissions": [
     {
       "resource": "device_list",
       "read": true,
       "write": true
     },
     {
       "resource": "server_info",
       "read": true,
       "write": true
     },
     {
       "resource": "user_management",
       "read": true,
       "write": true
     },
     {
       "resource": "port_info",
       "read": true,
       "write": true
     },
     {
       "resource": "server_configuration",
       "read": true,
       "write": true
     },
     {
       "resource": "activity_log",
       "read": true,
       "write": true
     },
     {
       "resource": "service_access",
       "read": true,
       "write": true,
       "sub_permissions": []
     },
     {
       "resource": "device_access",
       "read": true,
       "write": true,
       "sub_permissions": []
     },
     {
       "resource": "command_access",
       "read": true,
       "write": true
     },
     {
       "resource": "user_registration",
       "read": true,
       "write": true
     },
     {
       "resource": "property_access",
       "read": true,
       "write": true,
       "sub_permissions": []
     }
   ]
 },
 {
   "name": "guest",
   "key": null,
   "description": "Guest access with limited permission",
   "permissions": [
     {
       "resource": "device_list",
       "read": true,
       "write": false
     },
     {
       "resource": "server_info",
       "read": true,
       "write": false
     },
     {
       "resource": "user_registration",
       "read": true,
       "write": true
     }
   ]
 }
]

POST

Adds or updates given group credentials. Format is the same as returned from GET request

Request format example

{
  "name": "house1",
  "key": null,
  "use_credentials_key": true
  "description": "House x control access",
  "permissions": [
    {
      "resource": "device_access",
      "read": false,
      "write": false,
      "sub_permissions": [
        {
          "resource": "ECL-10AC-BT-MBus-1.2.0-1880 50391825 (home-ecl)",
          "read": true,
          "write": true
        },
        {
          "resource": "EC-D16-20AHR-L2A-1.2.0-1879-1 50397185 (home-ecl)",
          "read": true,
          "write": true
        },
        {
          "resource": "EC-D16-20AHR-L2A-1.2.0-1879-1 50528257 (home-ecl)",
          "read": true,
          "write": true
        }
      ]
    }
  ]
}

200 Response format example

{"result": "OK"}

DELETE

Deletes group according to given filters. If multiple groups match the criteria, only first user is deleted to prevent accidental deletion

200 Response format example

{"result": "OK"}

/api/v1/credentials/groups/members

Provides group member information

Required permission - user_management

Parameter

Value

Description

Methods

key

string

group key

GET

filter

string

group name filter

GET

Example request URI(s):

  • /api/v1/credentials/groups/members?filter=admin

GET

Returns a list of user credentials that are members of the giver group

200 Response format example

[
 {
   "permissions": [],
   "key":  "30820122300D06092A864886F70D01010105000382010F003082010A0282010100C7E0A3BD9FA519446F2044E0E6F07573E0706BA576623C6F0C9A1783286F6
            3310BE3F2617D1833D2B525DD92CA39CFA14A08BA09DCC134F705908916C43D79A554921D006C16EEAAD1AEDC66E1E71E3A15E2D5E0365ED11A8EE0B8
            43282EEC9A56505949C31BBFBA7F662F94D58065204705536A0FC59FBBEDE9F13CCC1F7DA62CB7FB7176C4A4EC04D2657C38BEC771307BFBA54E5A7CA
            F0CF1973F42682AD995E9BA285E9112C6F9D88DF840656D75A7DB6A02B882028737F225E406179FBF6E4FC32E7FFF2A46FB0DC997661584BDCF8AFC8E
            A807581D79A434D1C06832A0EC01F7A47D49FE211EADEDCB4F4BF65B3F26808AE76A7F79D496D73C2F8ACF530203010001",
   "groups": [
     {
       "name": "admin",
       "key": null
     }
   ],
   "principal": "CN=IoT derived admin cert,OU=IoT,O=Isotel,L=Lj,ST=Lj,C=SI"
 }
]

/api/v1/manager/device/upgrade

Handles device firmware upgrade

Parameter

Value

Description

Methods

Example request URI(s):

  • /api/v1/manager/device/upgrade

POST

Perform firmware upgrade on a given device, and optionally:

  • Put device in bootloader mode before initiating upgrade

  • Close device connection after finishing upgrade

Request parameters:

  • vid : vendor ID filter

  • pid : product ID filter

  • serial : serial number filter (optional)

  • file: firmware file contents encoded in base64 format

  • timeout: timeout to complete operation in (s) (optional)

  • device: name of device in IoT (either full label or deviceX designation), used for setting bootloader mode and disconnecting the serial adapter after finishing (optional)

  • boot_param: device parameter that governs mode of operation

  • boot_value: device parameter value that is required to put it into bootloader mode

Request format example

{
       'vid': 0x5726,
       'pid': 0x1500,
       'serial':'S2P01-12345678-00',
       'file':file,
       'timeout':28,
       'device':'device0'
       'boot_param':'sys.firmware',
       'boot_value':'Bootloader'
}

200 Response format example

{"status": "OK", "message": "Firmware upgrade completed."}

408 Response format example

{"message": "Unable to complete upgrade: Timeout"}

500 Response format example

{"message": "Unable to complete upgrade: Error"}