TH | EN

RESTful API¶

Provides a way to connect the device to the platform via a RESTful API that uses HTTP protocol. The API functionality can be tested at (ทดสอบการทำงานของ API ได้ที่ https://trial-api.netpie.io). There are two groups of API’s that are currently available.

Device API¶

It is an API related to devices. Its domain name is https://api.netpie.io/v2/device. The details are as follows:

1. Publish messages to various topics, can be used in two ways:

Type 1: Topic is specified in the URL path.

EndPoint	https://api.netpie.io/v2/device/message/{any}/{topic}
Method	PUT
Request Header	Authorization : Device ClientID:Token
Request Body	Content-type : text/plain \| Message to Publish to Topic
Return	Response Object `status` => Response Code (HTTP Response Code) `message` => Reply message

Example

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

Host: api.netpie.io/v2/device

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

Type 2: Specify Topic through parameter (Query string)

EndPoint	https://api.netpie.io/v2/device/message
Method	PUT
Request Header	Authorization : Device ClientID:Token
Parameter	`topic` : string is the Topic you want to publish messages to {{any}/{topic}}
Return	Response Object `status` => `message` => Reply message

Example

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

Host: api.netpie.io/v2/device

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

OFF

Caution

Setting Topic in the REST API is different from that of MQTT protocol. If the message is sent via REST, you need not put “@msg” at the front in the Topic, as the system will autocomplete for you. But, if you are sending a message via MQTT, you still need to add the prefix “@msg” in the Topic.

2. Reading the Shadow Data of the Device (Must be a Device belonging to the same Group)

EndPoint	https://api.netpie.io/v2/device/shadow/data
Method	GET
Request Header	Authorization : Device ClientID:Token
Parameter	`alias` : Name of the device of the shadow you want to read. (if it reads your shadow, don’t send this parameter)
Return	Response Object `status` => Response Code (HTTP Response Code) `data` => Device Shadow Data (JSON)

Example

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

Host: api.netpie.io/v2/device

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

3. Writing Data to Shadow Data as Merge

EndPoint	https://api.netpie.io/v2/device/shadow/data
Method	PUT
Request Header	Authorization : Device ClientID:Token
Parameter	`alias` : Device name of the shadow that you want to write. (If writing to your own shadow, don’t send this parameter)
Request Body	The data that you want to write to the Shadow Data will be in json format as follows: { "data": { "field name 1": value1, "field name 2": value2, ..., "field name n": value n } }
Return	Response Object `status` => Response Code (HTTP Response Code) `data` Device Shadow Data (JSON) update information

Example

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

Host: api.netpie.io/v2/device

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

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

4. Writing Data to Shadow Data as to Overwrite (Overwrite)

EndPoint	https://api.netpie.io/v2/device/shadow/data
Method	POST
Request Header	Authorization : Device ClientID:Token
Parameter	`alias` : Device name of the shadow that you want to overwrite. (If writing to your own shadow, don’t send this parameter)
Request Body	The data that you want to write to Shadow Data will be in JSON format as follows: { "data": { "field name 1": value1, "field name 2": value2, ..., "field name n": value n } }
Return	Response Object `status` => Response Code (HTTP Response Code) `data` => Device Shadow Data (JSON) update information

Example

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

Host: api.netpie.io/v2/device

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

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

Data Store API¶

It is an API used to retrieve data stored in the Time-Series database. The API’s domain name is https://ds.netpie.io/feed. The database used is KairosDB. The parameters will be sent in the same format as KairosDB

EndPoint	https://ds.netpie.io/feed/api/v1/datapoints/query
Method	POST
Request Header	Authorization : Bearer UserToken or Device ClientID:DeviceToken, Content-Type : `application/json`
Request Body	The terms used in the query are JSON format and can be classified into two types: Query Properties include : `start_absolute` => Start time in milliseconds. `start_relative` => Start time relative to current time. The units can be milliseconds, seconds, minutes, hours, days, weeks, months, and years. For example, if the start time is 5 minutes, the data points returned will be in the last 5 minutes. `end_absolute` => End time in milliseconds and must be greater than `start_absolute`. `end_relative` => Specify end time relative to the current time. Units can be 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, then the data points returned will be in between the last 30 minutes, to last 10 minutes. If the end time is not specified, then it will take the current time and date. `time_zone` => Time zone for the data query period. If not specified, UTC will be used. (for time zone, NETPIE is set to GMT) Note : You need to mention values for `start_absolute` and `start_relative`. On other hand, values for `end_absolute` and `end_relative` can be optional. Metric Properties include : `name` => Name of the Metric to query data. Specify Device ID (ClientID) from NETPIE, which is a required action. `aggregators` => Aggregate or process data in various forms before returning the data point. The relevant parameters are as follows: name => The type of data processing format is “avg” (Average), “dev” (Standard Deviation), “count”, “first”, “gasps”, “histogram”, “lasts”, “least_squares”, “max”, “min”, “percentile”, “sum”, “diff” (Difference), “div” (Divide), “rate”, “sampler”, “scale”, “trim”, “save_as”, “filter”, “js_function” (JS Aggregator), “js_range” (JS A ggregator). See Kairosdb for more details. `tags` => Used for filtering required data on NETPIE. Format is, tags: {attr: {field 1, field 2, …, field n}} `group_by` => Group data query points. Can be organized by Tags, Time period, Data point value, or by Data bucket on NETPIE. `exclude_tags` => Will show Tag in the returned data. (true: show Tag as default, false: do not display Tag) `limit` => This limits the number of data points to query. `order` => Sorts the data points. (asc: ascending, des: descending). It will sort the actual data points first.
Return	Response Object Extract Successfully (status200) Query data is in JSON format Data retrieval failed (status400 or 500) 400 Bad Request => Bad request, such as incomplete or incorrect parameter sent. 500 Internal Server Error => If there is an error in retrieving data from the server side.

Example 1 Authorization with User Token:

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

Host: ds.netpie.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 Device Token:

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

Host: ds.netpie.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"
                                        }
                                }
                        ]
                }
        ]
}