TH | EN

RESTful API

It is a channel for devices to call platform services via a RESTful API that uses HTTP Protocol. It is suitable for use as a channel for integrating existing systems or new ones that are about to be developed, regardless of the programming language they are developed from (test the API at (ทดสอบการทำงานของ API ได้ที่ https://beta-api.nexiiot.io)). The APIs currently available are divided into 2 groups as follows:


Device API

It is an API related to Device. The domain name of the API is https://api.nexiiot.io/device. The details are as follows:

1. Requesting the Device Platform Connection Status (Device Status)

EndPoint

https://api.nexiiot.io/device/status

Method

GET

Request Header

Authorization : Device ClientID:Token

Return
Response Object

  • deviceid is the Device ID.

  • alias is the name of the Device.

  • groupid is a Group ID of device.

  • projectid is a Project ID of device.

  • status is the connection status of the Device to the Platform (1 = connected or online, 0 = not connected or offline).

  • hashtag is a keyword used to filter data.

  • tags is a Key-Value used to filter data.

  • enabled indicates the status of the Device Key activation (true = enabled and can connect to the Platform, false = disabled and cannot connect to the Platform)

  • banned indicates the status of being suspended by the system (true = suspended and cannot connect to the Platform, false = not suspended and can connect to the Platform)

example

GET /device/status HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

2. Publishing messages to various topics can be done in 2 ways

  • Type 1 is specifying the Topic in URL Path format.

EndPoint

https://api.nexiiot.io/device/message/{any}/{topic}

Method

PUT

Request Header

Authorization : Device ClientID:Token

Request Body
Content-type : text/plain | The text you want to publish to the Topic.

Return
Response Object

  • status is HTTP Response Code

  • message is HTTP Response Message

example

PUT /device/message/mythings/bedroom/light HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

ON


  • Type 2 is specifying a Topic through a Parameter (Query String).

EndPoint

https://api.nexiiot.io/device/message

Method

PUT

Request Header

Authorization : Device ClientID:Token

Parameter

topic :string is the topic to which you want to publish the message ({any}/{topic})

Return
Response Object

  • status is HTTP Response Code

  • message is HTTP Response Message

example

PUT /device/message?topic=mything/bedroom/light HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

OFF


3. Publishing a private message to a specific device. There are 2 ways to use the device.

  • Type 1 is specifying the Topic in URL Path format.

EndPoint

https://api.nexiiot.io/device/private/{any}/{topic}

Method

PUT

Request Header

Authorization : Device ClientID of the device to which you want to send the message:Token of the device to which you want to send the message

Request Body
Content-typetext/plain

  • Private message that you want to publish to the desired device under the specified topic.

Return
Response Object

  • status is HTTP Response Code

  • message is HTTP Response Message

example

PUT /device/private/topic/for/me HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

Hello Device


  • Type 2 is specifying a Topic through a Parameter (Query String).

EndPoint

https://api.nexiiot.io/device/private

Method

PUT

Request Header

Authorization : Device ClientID of the device to which you want to send the message:Token of the device to which you want to send the message

Parameter

topic :string is the topic to be published private message to ({any}/{topic})

Return
Response Object

  • status is HTTP Response Code

  • message is HTTP Response Message

ตัวอย่าง

PUT /device/private?topic=topic/for/me HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

Hello Device


Caution

Sending a message via the REST API with a Topic is slightly different from sending via the MQTT Protocol. If sending via the REST API, the Topic setting does not need to include "@msg" in front, but the system will automatically fill it in. If sending via the MQTT Protocol, you must include "@msg" in front of the Topic to be sent.

Sending a Private Message The device that is being sent the message must subscribe to the topic with the prefix @private in front of the topic that you want to subscribe to, such as @private/topic/for/me or using @private/# will allow you to receive a Private Message in every topic.


4. Reading Device Shadow Data

EndPoint

https://api.nexiiot.io/device/shadow/data

Method

GET

Request Header

Authorization : Device ClientID:Token

Return
Response Object

  • status is HTTP Response Code

  • data is the Device Shadow Data (JSON).

example

GET /device/shadow/data?alias=sensor HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234


5. Writing data to Shadow Data using merge method

EndPoint

https://api.nexiiot.io/device/shadow/data

Method

PUT

Request Header

Authorization : Device ClientID:Token

Request Body

The data to be written to Shadow Data is in JSON format as follows:

{
        "data": {
                "field name 1": value1,
                "field name 2": value2, ...,
                "field name n": value n
        }
}

Return
Response Object

  • status is HTTP Response Code

  • data is the updated Device Shadow Data (JSON).

example

PUT /device/shadow/data?alias=test HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{
        "data": {
                "temperature": 33.7,
                "config": {"item1": "a", "item2": "b"},
                "note": "test case"
        }
}

6. Writing data to Shadow Data using overwrite method

EndPoint

https://api.nexiiot.io/device/shadow/data

Method

POST

Request Header

Authorization : Device ClientID:Token

Request Body

The data to be written to Shadow Data is in JSON format as follows:

{
        "data": {
                "field name 1": value1,
                "field name 2": value2, ...,
                "field name n": value n
        }
}

Return
Response Object

  • status is HTTP Response Code

  • data is the updated Device Shadow Data (JSON).

example

POST /device/shadow/data?alias=test HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{
        "data": {
                "temperature": 33.7,
                "config": {"item1": "a", "item2": "b"},
                "note": "test case"
        }
}

Shadow Batch Update

It is used in cases where the IoT Device cannot send data to the Cloud Platform at the specified time, such as due to internet connection problems, etc. This causes the IoT Device to store data in its own memory first, such as on an SD Card, etc. When the Cloud Platform can be connected, all stored data is sent to the Cloud Platform again. Values ​​can be sent to the Platform at multiple points at the same time.

There are 3 ways to write batch shadows:

  1. REST API is a data writing in batches, which is done through a REST API, which can be written in either a merge or overwrite format. The details are as follows:

EndPoint

https://api.nexiiot.io/device/shadow/batch

Method

PUT (Merge) or POST (Overwrite)

Request Header

Authorization : Device ClientID:Token

Request Body

The data set to be written to Shadow is in JSON format as follows:

{
        "batch" : [
                {"data":{ Shadow Data 1 }, "ts": time 1},
                {"data":{ Shadow Data 2 }, "ts": time 2}, ...,
                {"data":{ Shadow Data n }, "ts": time n}
        ],
        "merged": true or false
}

Return
Response Object

  • deviceid Refers to the ClientID of the Device whose Shadow is being written.

  • response Refers to the summary of the Shadow update (JSON).

example

POST /device/shadow/batch HTTP/1.1

Host: api.nexiiot.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{
        "batch" : [
                {"data":{"temp":25.9, "humid":9.6}, "ts":-90000},
                {"data":{"temp":25.3, "humid":9.8}, "ts":-60000},
                {"data":{"temp":24.5, "humid":9.1}, "ts":-30000},
                {"data":{"temp":26.8, "humid":8.2}, "ts":0 }
        ]
}

Note

The time of each data set is in milliseconds. You can use ts or timestamp as the field name. If the value is less than 1000 * 2^23 = 8388608000, it is considered a relative time with the current time. If the value is greater, it is considered an absolute time. You can use negative values to represent the past time, which is suitable for updating past data points. For example, if ts or timestamp is set to -90000 and the current timestamp is 1619075885, the time of the data point will be 1619075885 - 90000 = 1618985885 (90 seconds back from the present).


The merged field specified in the payload when writing to the Shadow determines the data writing method—whether to merge or overwrite.

  • If merged : true is set, the data will be merged.

  • If merged : false is set, the data will be overwritten.

  • If this field is not specified in the payload, the default value is true, meaning the data will be merged.


The operation of the Expression defined in the Schema and Trigger when writing to the Shadow in batch mode.

The Expression will still be calculated according to the formula defined for each data set, similar to a For Loop writing to the Shadow. However, when writing to the Shadow in batch mode, the Shadow read/write quota will only be deducted as 1 operation. The Shadow Expression quota will still be deducted according to the number of data sets. For example, if 100 data points are sent for storage and there is 1 field with an Expression set, the number of Shadow Expressions deducted will be 1 x 100 = 100 operations.

For Triggers, they will only operate on the data set with the latest value (the highest timestamp). The quota will be deducted as if writing only a single data set.


  1. MQTT is a batch writing method that uses Topic and Payload. See Shadow Batch Update


  1. CoAP API is a batch write operation that is performed via CoAP Protocol, which can be either merged or overwritten. See Shadow Batch Update


Caution

The limitation of writing to the Shadow in batch mode is that the number of data sets sent for writing at a time must not exceed 100 data sets (the batch field in the JSON array). For example, the payload sent for writing data is:


{ "ackid" : 1839, "batch" : [ {"data":{"temp":25.9, "humid":9.6}, "ts":-90000}, {"data":{"temp":25.3, "humid":9.8}, "ts":-60000}, {"data":{"temp":24.5, "humid":9.1}, "ts":-30000}, {"data":{"temp":26.8, "humid":8.2}, "ts":0}], "merged": true }


This means there are 4 data sets, for example. If the number of data sets sent exceeds the specified limit, none of the data will be saved, and a warning message will be returned in JSON format as follows:


{"ackid":140,"errcode":429,"message":"batch size exceeds 100","inputsize": 102}


This means that the Batch write with ackid 140 sent more than 100 data sets, specifically 102 data sets.


Data Store API

It is an API related to retrieving data stored in Timeseries Data. The API's domain name is https://ds.nexiiot.io/feed. The database used for storage is KairosDB. The query format of the various parameters sent is the same as KairosDB. The details are as follows:

EndPoint

https://ds.nexiiot.io/feed/api/v1/datapoints/query

Method

POST

Request Header

Authorization : Bearer UserToken or Device ClientID:DeviceToken, Content-Type : application/json

Request Body

Conditions used in queries are in JSON format and can be divided into 2 types:

  1. Query Properties include:

    • start_absolute is the start time in milliseconds.

    • start_relative is the start time relative to the current time by subtracting the current time from the specified time, as a number and in units of time. Possible units are milliseconds, seconds, minutes, hours, days, weeks, months, and years. For example, if the start time is 5 minutes, the returned data point will be within the past 5 minutes.

    • end_absolute is the end time in milliseconds and must be greater than start_absolute

    • end_relative Specifies an end time relative to the current time by subtracting the current time from the specified time, as a number and in units of time. Possible units are milliseconds, seconds, minutes, hours, days, weeks, months, and years. For example, if the start time is 30 minutes and the end time is 10 minutes, the data point returned will be between the last 30 minutes and the last 10 minutes. If no end time is specified, the current date and time are assumed.

    • time_zone is the time zone for the time of the data query. If not specified, UTC will be used (for time_zone NEXIIOT Platform, GMT will be used).

    Note

    start_absolute and start_relative must specify a value, but only one value can be used. end_absoluteAnd and end_relativeis is optional. If it is specified, only one value can be used.

  2. Metric Properties include:

    • name The name of the Metric that you want to query data for, specify it as DeviceId (Client ID of Device) from NEXIIOT Platform (required).

    • aggregators It is an array of settings for combining or processing data in various forms before returning data points. The related parameters are as follows:

      • name is the type of the data processing format: "avg" (Average), "dev" (Standard Deviation), "count", "first", "gaps", "histogram", "last", "least_squares", "max", "min", "percentile", "sum", "diff" (Difference), "div" (Divide), "rate", "sampler", "scale", "trim", "save_as", "filter", "js_function" (JS Aggregator), "js_filter" (JS Aggregator), "js_range" (JS Aggregator). See kairosdb

    • tags is for filtering the data you want by Tag in NEXIIOT Platform. Specify the desired Data Field. Format is tags : { attr: [ field_1, field_2, ..., field_n ] }

    • group_by is a grouping of data points in a query, which can be organized by Tag, Time Range, Data Point Value, or by Data Bucket. In NEXIIOT Platform, Tags are used to group data (separated by Data Field).

    • exclude_tags Indicates whether to include the Tag in the returned data (true = include Tag and which is the default, false = do not include Tag)

    • limit is a limitation on the number of data points to be queried by limiting the actual number of data points before aggregators

    • order คือ การเรียงลำดับจุดข้อมูล (asc คือ เรียงจากน้อยไปมาก, desc คือ เรียงจากมากไปน้อย) โดยจะเรียงลำดับจุดข้อมูลจริงก่อนจะทำ aggregators- name คือ ชื่อของ Metric ที่ต้องการ Query ข้อมูล ให้ระบุเป็น DeviceId (Client ID ของ Device) จาก NEXIIOT Platform (ต้องระบุ)

    • aggregators คือ Array ของการตั้งค่าการรวมหรือประมวลผลข้อมูลในรูปแบบต่างๆ ก่อนส่งจุดข้อมูลกลับมา ซึ่ง Parameters ที่เกี่ยวข้องมีดังนี้

      • name is the type of the data processing format: "avg" (Average), "dev" (Standard Deviation), "count", "first", "gaps", "histogram", "last", "least_squares", "max", "min", "percentile", "sum", "diff" (Difference), "div" (Divide), "rate", "sampler", "scale", "trim", "save_as", "filter", "js_function" (JS Aggregator), "js_filter" (JS Aggregator), "js_range" (JS Aggregator). See kairosdb

    • tags This is for filtering the data you want by Tag in NEXIIOT Platform. Specify the desired Data Field. Format is tags : { attr: [ field_1, field_2, ..., field_n ] }

    • group_by It is a grouping of data points in a query, which can be organized by Tag, Time Range, Data Point Value, or by Data Bucket. In NEXIIOT Platform, Tags are used to group data (separated by Data Field).

    • exclude_tags That is, do you want to display the Tag in the returned data or not? (true display the Tag as the default value, false do not display the Tag)

    • limit It is a limitation on the number of data points to be queried by limiting the actual number of data points before aggregators

    • order Refers to the sorting order of data points (asc = ascending, desc = descending), where the data points are sorted before applying aggregators.

Return
Response Object
  • Data retrieval successful (status200)

    • The data that the query receives is in JSON format.

  • Data fetch failed (status400 or 500)

    • 400 Bad Request is an invalid request, such as sending incomplete or incorrect parameters.

    • 500 Internal Server Error means if there is an error in retrieving data on the server side.

Example 1 Authorization with UserToken:

POST /api/v1/datapoints/query HTTP/1.1

Host: ds.nexiiot.io/feed

Authorization: Bearer AyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.AyJjdHgiOnsib3duZXIiOiJVOTc0ODE0NzczMjA0In0sInNjb3BlIjpbX SwiaWF0IjoxNTcxMzc1ODk4LCJuYmYiOjE1NzEzNzU4OTgsImV4cCI6MTU3MTQ2MjI5OCwiZXhwaXJlSW4iO jg2NDAwLCJqdGkiOiIzRk50VkVmVCIsImlzcyI6ImNlcjp1c2VydG9rZW4ifQ.AtbhSRgGXCjiQk4wENMD4KQ3uf Dof7HnzHY5Rcli0y0LpTJEDLklM-AmsAVzBnPBnJh9L3LvSGODc9xrYWotcA

Content-Type: application/json

{
        "start_relative": { "value":1, "unit":"days" },
        "metrics":[
                {
                        "name":"Aaa5d93b-Ae16-455f-A854-335AAAA16256",
                        "tags":{"attr":["temp", "humit"]},
                        "limit":50,
                        "group_by":[{ "name":"tag", "tags":["attr"] }],
                        "aggregators":[
                                {
                                        "name":"avg",
                                        "sampling": {
                                                "value":"1",
                                                "unit":"minutes"
                                        }
                                }
                        ]
                }
        ]
}

Example 2 Authorization with ClientID and DeviceToken:

POST /api/v1/datapoints/query HTTP/1.1

Host: ds.nexiiot.io/feed

Authorization: Device Aaa5d93b-Ae16-455f-A854-335AAAA16256:TuZfsgosxxxxx3br4Qt1Do9jvzLM5hZQ

Content-Type: application/json

{
        "start_relative": { "value":1, "unit":"days" },
        "metrics":[
                {
                        "name":"Aaa5d93b-Ae16-455f-A854-335AAAA16256",
                        "tags":{"attr":["temp", "humit"]},
                        "limit":50,
                        "group_by":[{ "name":"tag", "tags":["attr"] }],
                        "aggregators":[
                                {
                                        "name":"avg",
                                        "sampling": {
                                                "value":"1",
                                                "unit":"minutes"
                                        }
                                }
                        ]
                }
        ]
}