In this chapter, we describe the basic matters required when to use the Servwatch API.
Glossary
Device
Device means the barematal server or cloud instances.
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.
The contents of the device can be obtained by the device service
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.
The contents of the device can be obtained by the channel service
Metrics
Metrics are various performance data sent by the device (server). (Example: CPU idle)
The data format must be written in JSON object format.
Metrics are stored for each channel ID mapped to the device.
The metrics can be obtained by the Stream service
Using API
The device (server) and Servmetry communicate using the MQTT protocol, and the application and Servmetry use the HTTP (S) protocol.
The REST API (HTTP / HTTPS protocol) is called by the application to manage devices and read metrics.
The following APIs are available depending on the application.
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.
Protocol | Security | Resource requirement for devices |
---|
HTTP/MQTT | Poor(Non-encryption) | Low |
HTTPS/MQTTS | Excellent(Avoid men-in-middle attack) | High(Use more memory and CPU cycles..) |
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.
fig.2 Token overview
トークンの役割:
Token type: | REST API | HTTP/MQTT connector |
---|
API Token | Can use | - |
Device Token | - | Can use |
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: