ここでは、ServwatchのREST APIを使う上での基本的な決まりを解説します。

用語の説明

デバイス

デバイスはServwatchの監視対象ホストの最小単位です。

基本的にデバイスはServwatchエージェントにより自動登録されますが、手動登録することも可能です。

いずれの場合もデバイス作成後はメトリクスをストアするチャネルにマップする必要が生じます。

• 手動登録
  例：管理コンソールから手動でデバイスIDを登録した場合

• 自動登録（オートプロビジョニング）
  例：エージェントがServwatchにデバイスを自動登録した場合

デバイスの内容はdevice serviceにより取得することができます。

チャネル

Channel（チャネル）はデバイスからのデータを蓄積する論理チャネルです。

チャネルIDは常に整数値で指定されます。

チャネルはスキーマレスなJSONオブジェクトを格納可能な時系列データベースです。

チャネルの内容はchannel serviceにより取得することができます。

メトリクス

メトリクスはデバイス（サーバ）が送信した各種パフォーマンスデータです。（例：CPU idle）

データフォーマートはJSONオブジェクト形式で記述する必要があります。

メトリクスはデバイスにマップされたチャネルID毎にストアされます。

メトリクスはStream serviceにより取得することができます。

APIについて

デバイス(サーバ）とServmetry間はMQTTプロトコルにより通信を行い、アプリケーションとServmetry間はHTTP(S)プロトコルを利用します。

REST API（HTTP/HTTPSプロトコル）はアプリケーションから呼び出され、デバイスの管理やメトリクスの読み取りを行います。

APIは用途により、以下が用意されています。

• Device service:デバイスの管理・チャネルマップ・アクティベーション

• Channel service:メトリクス格納チャネルの管理

• Stream service:メトリクスの参照

• Event service:イベント処理（しきい値の設定・外部システムへの通知）の設定

• User service:ユーザ情報(メールアドレス・トークン情報etc）の参照・設定

APIのバージョニング

APIバージョンはエンドポイントURIに規定されています。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.

• Manual create
  Case:Create from Management Console.

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

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.

• Device service:manage devices,channel assign,activate

• Channel service:manage channel

• Stream service:Retrieve metrics

• Event service:manage threshold and notification

• User service:manage user profile

API versioning

API version is specified in endpoint URI.(e.g. https://m.thingscale.io/v2/<SERVICE_NAME>)

現在のAPIバージョン・リリースノートはCurrent API version and release note are here: Release Noteを参照してください。

セキュリティ

Security

All communication with ThingScale is performed over https(HTTP over TLS)により行われます。

これはServwatchとデバイス、アプリケーション間の通信が暗号化されて行われる事を保証します。

HTTP/MQTTデバイスコネクタは非力なデバイス（ゲートウェイ含む）のために非暗号化接続も利用可能です。

HTTP/HTTPS(MQTT/MQTTS)接続は長所と短所を含みますが、お使いの環境に応じて最適な方法をセキュリティ上のトレードオフも考慮して選択してください。

プロトコル

セキュリティ

デバイスに要求されるシステムリソース

HTTP/MQTT

脆弱（非暗号化接続）

低い

HTTPS/MQTTS

堅牢（暗号化接続 - 第3者による中間攻撃を防ぐ）

高い（より多くのメモリとCPU時間を必要とします。）

トークン

トークンはユーザ毎に割り当てられたREST API/デバイスコネクタの認証キーです。

APIトークンを利用する全てのケースにおいて、HTTPS(TLS)接続を利用されることを強く推奨します。

fig.2 トークン概略

Image Removed

トークンの役割：

.
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 Added

トークンの役割：

データフォーマットと日付の取り扱い

全てのAPIリクエストとレスポンスはJSONペイロードにて通知されます。

HTTP/MQTTデバイスコネクタはURLエンコード形式のペイロードを利用します。

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レートリミット

API/HTTPデバイスコネクタ使用時は同一IPアドレスからの秒間あたりのAPIリクエスト数に応じてレートリミット（流量制御）が適用されます。

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利用時のみHTTP ONLY)
  1 リクエストconnection/秒sec.