Created By: ThingScale
Created On: 13 Aug 2019
Overall Rating: Rating
Domain: IoT

The API is used to retrieve events, users, devices, sessions, and channels in JSON format.

API Endpoint:
  • Allows device to adding registry.
  • Maps device to time-series database.
  • Allows retrieving stream collections.
  • No SDK development with MQTT/REST.

  • Simplicity IoT development with APIs.

  • Scalable, secure platform as a service.

Frequently Asked Questions
  • What is the API version?

    API version is specified in endpoint URI(e.g.<SERVICE_NAME>). Current API version is 2.0.0.

  • What are the different Tokens used in this API?

    Tokens are per-user unique authorization 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: Use Device Token only when data is sent from device to ThingScale with HTTP/MQTT connector.

    Note: Device token is not per-device, per-user. This is in order to reduce the configuration task at the time of device distribution.

  • What is the API rate limit?

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

    Note: If the connection count has reached the upper limit, then API returns 429 Too Many Requests HTTP status code.

    • REST API: 20 requests/sec.
    • Device Connector(HTTP ONLY): 1 connection/sec.
  • What does Stream service offer?

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

    Note: alphanumeric value MUST BE ENCODED UTF-8.

  • What are the services offered by this API?

    ThingScale RESTful API is implemented as JSON over HTTP requests verbs GET/POST/PUT/DELETE. Currently, the APIs provide the following services.

    • 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.
  • How can the API be securely used?

    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, choose the right one depends on your environment and security trade-off.

    We STRONGLY RECOMMENDED HTTPS/MQTTS for secure connection.

    ProtocolSecurityResource requirement for MCUs
    HTTPS/MQTTSExcellent(Avoid men-in-middle attack)High(Use more memory and CPU cycles.)
  • What are the Data-format and timestamp accepted?

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

    Note: During stream retrieve, specify time range as local timezone(e.g. 'YYYY-MM-DD hh:mm).

  • What does Channel service offer?

    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 time-series database with schema less JSON objects, each stream can be specified labels and units.

  • What does Device service offer?

    Device means the WSN gateway or end device. The device will be activated manually, but it is also possible to activate automatically. It is required to map the device to the channel in any case.

    • Manual provision Case: Create from Management Console.
    • Auto provision Case: When you connect the device for the first time in ThingScale.







Loading Comments...