In this chapter, we describe the basic matters required when to use the API.

Glossary

Channel

Channel is a logical channel that stores the data transmitted from the device.
It is not to specify the channel directly from the device, you will be distributed from the device_id(device's serial).
Channel is a timeseries database with schema less JSON objects, each stream can be specified labels and units.

Stream

Stream is datapoints that send device's sensor data.(e.g. temperature)
Stream has numeric(integer or float) or alphanumeric(like RFID UID) value.
Data type is determine by platform side.

Data type sample:

12.5 : numeric
"Hello!" : string

{"temp" : 25, "humidity" : 50}  : JSON objects

Device

Device means the WSN gateway or end device.
The device basically manually activated, but it is also possible to activate automatically.
Requires there to map the device to the channel in any case.

• Manual create
  Case:Create from Management Console.

• Automatically create
  Case:When you connect the device for the first time in ThingScale.

Using API

ThingScale RESTful API is implemented as JSON over HTTP requests verbs GET/POST/PUT/DELETE.
Currently, APIs are provided below.

• Device service : manage devices,channel assign,activate

• Channel service : channel settings,manage metadata

• Stream service : Retrieve(Write) Stream

• Event service : manage threshold and notification

• User service : manage user profile

• Publish service : Publish MQTT messages to device

• Session service: Showing active pub/sub clients.

API Versioning

API version is specified in endpoint URI.(e.g. https://m.thingscale.io/v2/<SERVICE_NAME>)
Current API version and release note are here Release Note

Security

All communication with ThingScale is performed over https(HTTP over TLS).
This ensures that all communication between ThingScale and device is over an encrypted communication.
HTTP/MQTT device connector can use plain-http and non-encrypted TCP communication for small memory footprint MCUs.(MCU:Micro Control Unit)
HTTP/HTTPS both protocols have pros and cons, choosing the right one depend on your environment and security trade-off.

Token

Tokens are per-user unique authorize key for API/Device connector.
In all cases you want to use the API token, it is strongly recommended that you use the HTTPS(TLS) connection.

• API Token
  All RESTful API operation use API token.

• Device Token
  For use only data sending from device to ThingScale with HTTP/MQTT connector.
  

fig.2 Token Overview

Image Removed

Image Added

Role of Token:

Data-format and timestamps

All API requests and responses use the JSON payloads only.
HTTP and MQTT device connector use the URL Encodeded payloads.
All timestamps are relative to UTC.Timestamps format is ISO8601:2004 standard.

Sample

e.g. Stream response(TZ="Asia/Tokyo")

{"_id":"54d3fc256807f4a616acbb33","value":11.1,"value2":47.9,"value3":null,"value4":null,"at":"2015-02-06T08:26:29+0900"}

e.g. Device list response(TZ="Asia/Tokyo")

{
  "device_id": "1085266243",
  "description": "sensirion sht-25",
  "enable": "true",
  "mapped_ch": 0,
  "device_type": "Xbee Pro2",
  "location": "Niigata,Japan",
  "manufacturer": "Sensincs,llc",
  "activate_at": "2015-01-13T16:58:00+09:00"
}

API rate limit

API usage is rate limited by per-second API request numbers.
The device connector rate limit by per-minutes request numbers.

Current rate limit settings as follows:

• REST API
  20 requests/sec.

• Device Connector(HTTP ONLY)
  1 connection/sec.