Integration API User Guide

Code Examples

Included with the documentation are code examples, showing how to use Integration API on variety of programming platforms:

  • NodeJS: using server-side JavaScript
  • Python: using Python
  • C#: using Microsoft.NET platform and C# programming language
  • Bash: using Linux bash

All examples are architected in a very similar way, following the principles described below. Read them first, before diving into specific example.

Integration session

Integration session is a series of calls to Integration API endpoints, to obtain device data, change their settings or send commands.

Integration session must follow these steps:

  • Login, which returns session token
  • One or more calls to data or action endpoints
  • Log out

Session should be kept as short as possible. In any case, session token will expire unconditionally after 15 minutes, after which time another login is required. Therefore it is best to always follow the above flow and keep session duration to a minimum.

Configuration

The following configuration settings are required, to use Integration API:

  • API client name
  • API client identifier
  • User name
  • Password
  • API gateway URL
  • API endpoint URLs

You will obtain API client and user credentials from your reseller.

All these settings can change on a short notice. It is therefore recommended to keep them in separate configuration files, per each integration and environment. For example, in NodeJS implementation you can find the following configuration.prod.js file:

  const Configuration = {
  clientId: 'integration',
  clientKey: 'a5e56a54-2e66-49e3-a36c-30ea94c52076',
  name: '[email protected]',
  password: '',
  baseUrl: 'https://api3.stellacontrol.com',
  endpoint: {
    security: '/security',
    devices: '/devices'
  }
}

These settings are imported into actual integration client:

  import { Configuration } from './configuration.prod'
const apiClient = new APIClient(Configuration)

Request and response format

HTTP Headers

All calls to Integration API must carry the following HTTP headers:

  sc-api-client: API client identifier
sc-api-key:    API client key
Content-Type:  application/json

If your HTTP client supports HTTP response compression, you may also include

  Accept-Encoding: gzip, deflate

Requests

Integration API uses JSON as payload format for all requests. The exact content of request payload depends on the API endpoint, as described in details further.

Responses

All responses as returned as JSON. as payload format for all requests. The exact content of request payload depends on the API endpoint, as described in details further. Each response has the following format:

  {
  "source": {
    "name": "",
    "description": "",
    "version": ""
  },
  "requestId": "",
  ... other endpoint-specific data ..
}

For example, valid login request could return the following response:

    "source": {
    "name": "@security-api",
    "description": "Security API",
    "version": "1.0.221"
  },
  "requestId": "req-kgX3iDv0Uj",
  "message": "Third-party client [[email protected]] has logged in from [223.38.1.21]",
  "session": {
    ... session details ...
  }
}

Error Responses

Error responses are signalled by appropriate HTTP error codes. For example:

  • When user credentials are invalid, HTTP 401 Unauthorized is returned
  • When client calls endpoint for which permissions have not been granted, HTTP 403 Forbidden is returned
  • Server-side errors are signalled with HTTP 500 Server Error
  • etc.

JSON payload described above is returned with error responses as well. It usually carries additional error details, so it’s worth investigating in your integration code.

Establishing session

Before performing any other calls to Integration API, you must establish secure session and obtain session token, by calling /security/login endpoint:

Request:

  POST /security/login
  
  {
  "user": "your-user-name",
  "password": "your-password"
}

Response:

  {
  "message": "",
  "session": {
    "token": "",
    "expiresIn": 0,
    "user": {
      "name": "",
      ...
    }
  }
}
Field Description
message Login result
session.token Secure session token
session.expiresIn Time when session will expire, in seconds
session.user Details of the logged in user

Session token

You must keep the session token and pass it with each subsequent call to Integration API, using Authorization HTTP header, for example in the following way:

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5...Q1ZBU

Without this, calls will fail with HTTP 401 Unauthorized error.

Session token will automatically expire within fixed time, as returned with login request. Make sure that your session does not exceed this time.

Ending session

After your integration code has performed all tasks, you are required to call /security/logout endpoint. Notice that this, as any other authenticated endpoints, also requires session token passed as Autorization HTTP header:

Request:

  DELETE /security/logout
  
  {
  "name": "your-user-name",
  "sessionToken": "session-token"
}

Response:

  {
  "message": ""
}

Retrieving device data

To retrieve device data such as type, model, software and hardware version etc., use /devices/device endpoint:

Request:

  GET /devices/device/serial-number/<serialNumber>

for example

  GET /devices/device/serial-number/AC001923

Response:

  {
  "device": {
    "id": "",
    "serialNumber": "",
    "type": "",
    "model": "",
    "model": "",
    "firmwareVersion": "",
    "hardwareVersion": "",
    ...
  }
}

Retrieving device status

To retrieve the most recent device status, use /devices/device/status endpoint.

Depending on device settings, the returned status can be between 1 second to 10 minutes old, assuming that the device is connected to internet and currently online. If device is disconnected or has intermittent connectivity issues, returned status might be older than that.

Request:

  GET /devices/device/serial-number/<serialNumber>/status

for example

  GET /devices/device/serial-number/AC001923/status

Response:

  {
    "serialNumber": "",
    "status": {
      "version": "",
      "connection": { ... },
    ...
  }
}

The exact content of the status property can vary and depends on many factors such as:

  • Device type and model
  • Firmware version
  • Whether certain functionality is currently enabled or disabled on the device

An example of device status payload can be found in examples in device-status.json.

Please notice that device status payload can and will change in future versions of the firmware. Changes will be indicated by a new version number of the protocol, specified in status.version variable. When implementing integrations, always check the status.version variable whether it matches your code. Contact your reseller for the details and intepretation of the returned parameters or changes in the protocol.

Recalibrating device

To send recalibrate command to a device, use /devices/device/recalibrate endpoint.

Request:

  POST /devices/device/serial-number/<serialNumber>/recalibrate

for example

  POST /devices/device/serial-number/AC001923/recalibrate

Response:

  {
  "success": true|false,
  "results": [
    {
      "success": true|false,
      "serialNumber": "",
      "id": "",
      "result": ""
    },
    {
      "success": true|false,
      "serialNumber": "",
      "id": "",
      "result": ""
    },
    ...
  ]
}
Field Description
success Indicates whether command has been succesfully queued for delivery
results Array of command results, one per each impacted device
results[].success Indicates whether command has been succesfully queued for delivery to the device
results[].serialNumber Serial number of the device
results[].result Further details, such as command reference ID

Recalibrating multiple devices

To recalibrate multiple devices at once, use the same devices/device/recalibrate endpoint but specify the list of devices in request payload instead of the URL:

Request:

  POST /devices/device/recalibrate

Request body:

  {
	"devices": [
		{ "serialNumber": "AC001923" },
		{ "serialNumber": "AC001924 " },
		{ "serialNumber": "AC001925 " }
	]
}

Response format is the same as for any other command.

Rebooting device

To send reboot command to a device, use /devices/device/reboot endpoint.

Request:

  POST /devices/device/serial-number/<serialNumber>/reboot

for example

  POST /devices/device/serial-number/AC001923/reboot

Response format is the same as for any other command.

Rebooting multiple devices

To reboot multiple devices at once, use the same devices/device/reboot endpoint but specify the list of devices in request payload instead of the URL:

Request:

  POST /devices/device/reboot

Payload format is the same as for RECALIBRATE command sent to multiple devices.

Response format is the same as for any other command.

Toggle device bands

To turn device bands on and off, use /devices/device/bands endpoint.

Request:

  POST /devices/device/serial-number/<serialNumber>/bands

for example

  POST /devices/device/serial-number/AC001923/bands

Specify identifiers of bands and their requested status in the request payload. To turn the band on, use true. To turn the band off, use false.

  {
	"07": true|false,
	"08": true|false,
	"09": true|false,
	"18": true|false,
	"21": true|false,
	"26": true|false
}

The identifiers above indicate bands to turn on and off. You only have to specify the bands you want to toggle, other bands which should remain the same, can be ignored in the payload. The sequence of bands listed in the payload does not matter.

For example, to switch off bands 21 and 26, while turning on band 07 you can use the following payload:

  {
  "21": false,
	"26": false,
	"07": true
}

Supported band identifiers:

Identifier EU Frequency US Frequency
07 700 MHz N/A
08 800 MHz APT700
09 900 MHz 850 MHz
18 1800 MHz AWS-1750
21 2100 MHz PCS-1900
26 2600 MHz 2600 MHz

Response format is the same as for any other command.

Toggle bands on multiple devices

To turn bands on and off, on multiple devices at once, use the same devices/device/reboot endpoint but with a different payload, specifying every device and its set of bands to toggle:

Request:

  POST /devices/device/bands
  
  {
  "devices": [
    {
      "serialNumber": "",
      "07": true|false,
      "08": true|false,
      "09": true|false,
      "18": true|false,
      "21": true|false,
      "26": true|false
    },
    {
      "serialNumber": "",
      "07": true|false,
      "08": true|false,
      "09": true|false,
      "18": true|false,
      "21": true|false,
      "26": true|false
    },
    ...
  ]
}

Like with toggling bands on a single device, you only have to specify bands which you want to turn on and off. Also here, the sequence of bands in the payload does not matter.

Response format is the same as for any other command.

Changing bands attenuiation

To turn device bands on and off, use /devices/device/bands/attenuation endpoint.

Request:

  POST /devices/device/serial-number/<serialNumber>/bands/attenuation

for example

  POST /devices/device/serial-number/AC001923/bands/attenuation

Specify identifiers of bands and their requested attenuation values in the request payload.

  {
	"07": 0,
	"08": 0,
	"09": 3,
	"18": 10,
	"21": 0,
	"26": 5
}

The identifiers above indicate bands to configure. You only have to specify the bands you want to change. Ignore other bands for which you don’t want to change the attenuation values.

For example, to configure only bands 21 and 26, you can use the following payload:

  {
  "21": 10,
	"26": 10
}

Response format is the same as for any other command.