Difference between revisions of "IoTGateway/RESTful APIv2"

From ESS-WIKI
Jump to: navigation, search
(→‎REST Resource)
(→‎Linear Dust WSN Resources)
Line 252: Line 252:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/Setting
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 282: Line 280:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting</nowiki>
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/IoTGW/WSN/<mac addr>/Setting
 
 
|}
 
|}
  
Line 293: Line 289:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 311: Line 305:
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"1234"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"1234"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID</nowiki>
  
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"sv":"1234"}' -t /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID
 
 
|}
 
|}
 
=== Set a new Join Key for the WSN manager. ===
 
=== Set a new Join Key for the WSN manager. ===
Line 321: Line 313:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 338: Line 328:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"DUSTNETWORKSROCK"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"DUSTNETWORKSROCK"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey</nowiki>
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"sv":"DUSTNETWORKSROCK"}' -t /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey
 
 
|}
 
|}
 
=== Retrieve the WSN manager information. ===
 
=== Retrieve the WSN manager information. ===
Line 348: Line 336:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Info
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Info
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/Info
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 394: Line 380:
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info</nowiki>
  
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/IoTGW/WSN/<mac addr>/Info
 
 
|}
 
|}
 
=== Reset the WSN manager. ===
 
=== Reset the WSN manager. ===
Line 404: Line 388:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 421: Line 403:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset</nowiki>
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"bv":1}' -t /WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset
 
 
|}
 
|}
 
=== Retrieve the WSN Network Statistics. ===
 
=== Retrieve the WSN Network Statistics. ===
Line 431: Line 411:
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics
 
| URI Resource Path || /WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 470: Line 448:
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics</nowiki>
  
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics
 
 
|}
 
|}
 
=== Retrieve the Sensor Hub information. ===
 
=== Retrieve the Sensor Hub information. ===
Line 480: Line 456:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Info
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 511: Line 485:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info</nowiki>
−
 
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/<mac addr>/SenHub/Info
 
  
 
|}
 
|}
Line 523: Line 494:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info/Name
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info/Name
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Info/Name
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 540: Line 509:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"Motion123"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/Name</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"sv":"Motion123"}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/Name</nowiki>
−
 
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"sv":"Motion123"}' -t /WSNMgmt/<mac addr>/SenHub/Info/Name
 
  
 
|}
 
|}
Line 552: Line 518:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info/reset
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Info/reset
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Info/reset
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 570: Line 534:
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/reset</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/reset</nowiki>
  
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"bv":1}' -t /WSNMgmt/<mac addr>/SenHub/Info/reset
 
 
|}
 
|}
 
=== Retrieve the Sensor Hub available action. ===
 
=== Retrieve the Sensor Hub available action. ===
Line 580: Line 542:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Action
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Action
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Action
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 602: Line 562:
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action</nowiki>
  
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/<mac addr>/SenHub/Action
 
 
|}
 
|}
 
=== Set the Sensor Hub to AutoReport. ===
 
=== Set the Sensor Hub to AutoReport. ===
Line 612: Line 570:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Action/AutoReport
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Action/AutoReport
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Action/AutoReport
+
| Method|| POST
−
|-
 
−
| Method(HTTP/MQTT)|| POST/PUB
 
 
|-
 
|-
 
| Request JSON Data||  
 
| Request JSON Data||  
Line 629: Line 585:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":0}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action/AutoReport</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X POST -d '{"bv":0}' <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action/AutoReport</nowiki>
−
 
−
|-
 
−
| Example || mosquitto_pub -h <IP> -m '{"bv":0}' -t /WSNMgmt/<mac addr>/SenHub/Action/AutoReport
 
  
 
|}
 
|}
Line 641: Line 594:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/SenData
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/SenData
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/SenData
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 670: Line 621:
 
|-
 
|-
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/SenData</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/SenData</nowiki>
−
 
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/<mac addr>/SenHub/SenData
 
  
 
|}
 
|}
Line 682: Line 630:
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Net
 
| URI Resource Path || /WSNMgmt/<mac addr>/SenHub/Net
 
|-
 
|-
−
| MQTT Topic Format|| /WSNMgmt/<mac addr>/SenHub/Net
+
| Method|| GET
−
|-
 
−
| Method(HTTP/MQTT)|| GET/SUB
 
 
|-
 
|-
 
| Request JSON Data|| N/A
 
| Request JSON Data|| N/A
Line 715: Line 661:
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Net</nowiki>
 
| Example || curl -H "Content-Type: application/json" -X GET <nowiki>http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Net</nowiki>
  
−
|-
 
−
| Example || mosquito_sub -h <IP> -C 1 -t /WSNMgmt/<mac addr>/SenHub/Net
 
 
|}
 
|}
  

Revision as of 08:51, 28 June 2016

Introduction

The IoT Gateway exposes a comprehensive set of Web Service APIs for application integration purposes. The IoT Gateway REST API allows you to build applications that use Representational State Transfer HTTP calls to retrieve, modify, or publish platform data. For example through the APIs, you are able to access all the functionality of the Server or to control a device from your application built on top of the IoT Gateway.

The IoT Gateway conforms to standard REpresentational State Transfer (REST) protocol to expose its Application Programming Interfaces (API). REST has emerged over the past few years as a predominant Web service design model. REST-style architectures consist of clients and servers. Clients initiate requests to servers, while servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.

IoT Gateway RESTful APIs expose the standard action types (Create, Read, Update, and Delete) over the platform objects. They are capable of retrieving a resource representation in JSON format. You can use the REST HTTP Accept Header to specify the representation requested using the "application/json" Media Types.

Writing Web Services Client Applications

The IoT Gateway provides a REST-style API over HTTP (or HTTPS). Users can write HTTP clients in their preferred programming language that get data/services from the IoT Gateway and use or display the data in the way that they desire. Examples of such clients include Web pages and programs written in a language such as Python or Java. These clients send requests to the server using standard HTTP requests. The HTTP requests that IoT Gateway supports are GET, PUT, POST, and DELETE. The server supports basic HTTP authentication and only valid users can access the database. To reduce the authentication overhead of multiple requests, either use an HTTP library that caches cookies, or cache the cookies JSESSIONID and SID yourself.

In a Web Browser

Any GET request can be typed into the URL field of a web browser. Some browser plug-ins (chrome plugin, DHC - REST/HTTP API Client) also allow other HTTP methods to be called.

Restfulapi dhc.png

Python

Python scripts can be written to send standard HTTP requests to the server. These scripts use Python libraries to handle connecting to the server, sending the request, and getting the reply. Use urllib2 to send request

Example:

GET: 

 import urllib2
 import base64
 username = 'NAME'
 password = 'PWD'  
 url = 'http://localhost/restapi/AccountMgmt/AccountInfo'
 base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
 req = urllib2.Request(url)
 req.add_header("Authorization", "Basic %s" % base64string)
 req.add_header('Content-type', 'application/json')
 response = urllib2.urlopen(req).read()
 print(response)

PUT: 

 import urllib2
 import base64
 username = 'NAME'
 password = 'PWD'  
 url = 'http://localhost/restapi/AccountMgmt/AccountConfig'
 data = '{"username":"admin","password":"1234"}'
 base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
 req = urllib2.Request(url)
 req.get_method = lambda: 'PUT'
 req.add_header("Authorization", "Basic %s" % base64string)
 req.add_header('Content-Type', 'application/json')
 response = urllib2.urlopen(req, data).read()
 print(response)

C#

HTTP requests can be sent to the server through a Java program. The key classes are HttpWebRequest and HttpWebResponse from System.Net.

Example:

GET: 

 static string HttpGet(string url)
 {
     HttpWebRequest req = WebRequest.Create(url) as HttpWebRequest;
     req.Credentials = new System.Net.NetworkCredential("NAME", "PWD"); 
     string privilege = string.Format("{0}:{1}", acut, pwd);
     byte[] bytes = System.Text.Encoding.GetEncoding("utf-8").GetBytes(privilege);
     req.Headers.Add("Authorization", Convert.ToBase64String(bytes));
     req.Accept = "application/json";
     string result = null;
     using (HttpWebResponse resp = req.GetResponse() as HttpWebResponse)
     {
         StreamReader reader = new StreamReader(resp.GetResponseStream());
         result = reader.ReadToEnd();
     }
     return result;
 }

PUT: 

 static string HttpPost(string url)
 {
     HttpWebRequest req = WebRequest.Create(new Uri(url)) as HttpWebRequest;
     req.Credentials = new System.Net.NetworkCredential("NAME", "PWD"); 
     req.Method = "PUT";
     req.ContentType = "application/json";
     req.Accept = "application/json";
     string privilege = string.Format("{0}:{1}", acut, pwd);
     byte[] bytes = System.Text.Encoding.GetEncoding("utf-8").GetBytes(privilege);
     req.Headers.Add("Authorization", Convert.ToBase64String(bytes));
     StringBuilder paramz = new StringBuilder();
     paramz.Append("{\"username\":\"admin\",\"password\":\"1234\"}");
     byte[] formData = UTF8Encoding.UTF8.GetBytes(paramz.ToString());
     req.ContentLength = formData.Length;
     // Send Request:
     using (Stream post = req.GetRequestStream())
     {
         post.Write(formData, 0, formData.Length);
     }
     // Response:
     string result = null;
     using (HttpWebResponse resp = req.GetResponse() as HttpWebResponse)
     {
         StreamReader reader = new StreamReader(resp.GetResponseStream());
         result = reader.ReadToEnd();
     }
     return result;
 }

Java

HTTP requests can be sent to the server through a Java program. use java.net.URL and java.net.HttpURLConnection to send request.

Example:

GET: 

 private static void HttpGet(String urlstr)
 {
     String username = "NAME", password = "PWD";
     HttpURLConnection conn = null;
     String userPassword = username + ":" + password;   
     String encoding = new sun.misc.BASE64Encoder().encode(userPassword.getBytes());  
     try{
         URL url  = new URL(urlstr);
         conn = (HttpURLConnection)url.openConnection();
         conn.setRequestMethod("GET");
         conn.setRequestProperty("Accept", "application/json");
         conn.setRequestProperty("Authorization", "Basic " + encoding);  
         if (conn.getResponseCode() != 200) 
         {
             throw new RuntimeException("Failed : HTTP error code : "+ conn.getResponseCode());
         }
         BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream()))); 
         String output;
         System.out.println("Output from Server .... \n");
         while ((output = br.readLine()) != null) {
            System.out.println(output);
         } 
         conn.disconnect();
     }
     catch(Exception e) {}
 }

PUT: 

 private static void HttpPOST(String urlstr)
 {
     String username = "NAME", password = "PWD";
     HttpURLConnection conn = null;
     String userPassword = username + ":" + password;   
     String encoding = new sun.misc.BASE64Encoder().encode(userPassword.getBytes());  
     try{
         URL url  = new URL(urlstr);
         conn = (HttpURLConnection)url.openConnection();
         conn.setDoOutput(true);
         conn.setRequestMethod("PUT");
         conn.setRequestProperty("Content-Type", "application/json");
         conn.setRequestProperty("Accept", "application/json");
         conn.setRequestProperty("Authorization", "Basic " + encoding);  
         String input = "{\"username\":\"admin\",\"password\":\"1234\"}";
         OutputStream outputStream = conn.getOutputStream();
         outputStream.write(input.getBytes());
         outputStream.flush();
         if (conn.getResponseCode() != 200) 
         {
             throw new RuntimeException("Failed : HTTP error code : "+ conn.getResponseCode());
         }
         BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream()))); 
         String output;
         System.out.println("Output from Server .... \n");
         while ((output = br.readLine()) != null) {
             System.out.println(output);
         } 
         conn.disconnect();
     }
     catch(Exception e){}
 }

Javascript

use jQuery's $.ajax() to send request

Example: 

 $.ajax(
 {
     type: put,
     url: 'http://localhost/restapi/AccountMgmt/AccountConfig',
     data: '{"username":"admin","password":"1234"}',
     contentType: 'application/json',
     dataType: 'text',
     error: function(xhr, exception) 
     {
         //TODO   
     },
     beforeSend: function(xhr) 
     {
         xhr.setRequestHeader("Authorization", "Basic " + $.base64.encode(user + ":" + password));
     },
     success: function(response) 
     {                    
     }
 });

Web Services

URL Specification

IoT Gateway Web Services APIs are RESTful in nature. Every URL relates to a specific resource or list of resources.

RESTful API: http://<ip address>:port/restapi/<resource path>

Default Port: 3000

Default User Name: admin

Default Password: admin

All REST APIs use CRUD Conventions as follows:

Action Create Read Update Delete
HTTP VERB POST/PUT* GET PUT DELETE

Return Error Code

Catalog Error Code Description
Server Status 1001 Internal Sever Error
Input Argument and Data 1051 Input Invalid JSON
Service Access 1151 Invalid URL
Service Access 1152 Invalid Method

Example: 

 {
     "result": {
         "ErrorCode": "1051",
         "Description": "Input Invalid JSON"
     }
 }

REST Resource

Restfulapi resource.png

Linear Dust WSN Resources

Retrieve the WSN manager setting information.

Description Retrieve the WSN manager setting information.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/Setting
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"NetID",
           "sv":"2001",
           "asm":"rw"
        },
        {  
           "n":"JoinKey",
           "sv":"JOINADVANTECHIOT",
           "asm":"rw"
        },
        {  
           "n":"Interface",
           "v":1,
           "asm":"r"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting

Set a new Network ID for the WSN manager.

Description Set a new Network ID for the WSN manager.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID
Method POST
Request JSON Data 
{
 "sv":"1234"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"sv":"1234"}' http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/NetID

Set a new Join Key for the WSN manager.

Description Set a new Join Key for the WSN manager.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey
Method POST
Request JSON Data 
{
 "sv":"DUSTNETWORKSROCK"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"sv":"DUSTNETWORKSROCK"}' http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Setting/JoinKey

Retrieve the WSN manager information.

Description Retrieve the WSN manager information.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/Info
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"SenHubList",
           "sv":"00170d0000582cca,00170d0000306265",
           "asm":"r"
        },
        {  
           "n":"Neighbor",
           "sv":"00170d0000306265",
           "asm":"r"
        },
        {  
           "n":"Health",
           "v":100,
           "asm":"r"
        },
        {  
           "n":"Name",
           "sv":"WSN0",
           "asm":"r"
        },
        {  
           "n":"sw",
           "sv":"1.2.1.12",
           "asm":"r"
        },
        {  
           "n":"reset",
           "bv":0,
           "asm":"rw"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info

Reset the WSN manager.

Description Reset the WSN manager.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset
Method POST
Request JSON Data 
{
 "bv":1
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/Info/reset

Retrieve the WSN Network Statistics.

Description Retrieve the WSN Network Statistics.
URI Resource Path /WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "netstat":{  
        "NetReliability":100,
        "NetPathStability":97,
        "msNetLatency":400
     },
     "senhub":{  
        "e":[  
           {  
              "mac":"00170d0000582cca",
              "id":1,
              "stat":"OPER",
              "routing":"YES",
              "reliablity":100,
              "mslatency":0
           },
           {  
              "mac":"00170d0000306265",
              "id":2,
              "stat":"OPER",
              "routing":"YES",
              "reliablity":100,
              "mslatency":700
           }
        ]
     }
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/IoTGW/WSN/<mac addr>/NetworkStatistics

Retrieve the Sensor Hub information.

Description Retrieve the Sensor Hub information.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Info
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"Name",
           "sv":"Motion",
           "asm":"rw"
        },
        {  
           "n":"sw",
           "sv":"1.0.00",
           "asm":"r"
        },
        {  
           "n":"reset",
           "bv":1,
           "asm":"rw"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info

Set the Sensor Hub name.

Description Set the Sensor Hub name.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Info/Name
Method POST
Request JSON Data 
{
 "sv":"Motion123"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"sv":"Motion123"}' http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/Name

Reset the Sensor Hub.

Description Reset the Sensor Hub.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Info/reset
Method POST
Request JSON Data 
{
 "bv":1
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"bv":1}' http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Info/reset

Retrieve the Sensor Hub available action.

Description Retrieve the Sensor Hub available action.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Action
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"AutoReport",
           "bv":1,
           "asm":"rw"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action

Set the Sensor Hub to AutoReport.

Description Set the Sensor Hub to AutoReport.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Action/AutoReport
Method POST
Request JSON Data 
{
 "bv":0
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"bv":0}' http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Action/AutoReport

Retrieve the Sensor Hub all sensor data.

Description Retrieve the Sensor Hub all sensor data.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/SenData
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"Ultrasonic",
           "u":"cm",
           "v":408.00,
           "min":15,
           "max":645,
           "asm":"r",
           "type":"d",
           "rt":"ucum.cm",
           "st":"ipso",
           "exten":""
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/SenData

Retrieve the Sensor Hub network information.

Description Retrieve the Sensor Hub network information.
URI Resource Path /WSNMgmt/<mac addr>/SenHub/Net
Method GET
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "e":[  
        {  
           "n":"Health",
           "v":100,
           "asm":"r"
        },
        {  
           "n":"Neighbor",
           "sv":"00170d0000582cca",
           "asm":"r"
        },
        {  
           "n":"sw",
           "sv":"1.0.00",
           "asm":"r"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/WSNMgmt/<mac addr>/SenHub/Net

API Management Resources

Retrieve all API resources, and API version.

Description Retrieve all API resources, and API version.
URI Resource Path /APIInfoMgmt/APIInfo
MQTT Topic Format /APIInfoMgmt/<mac addr>/APIInfo
Method(HTTP/MQTT) GET/SUB
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "Mgmt":{  
        "item":[  
           "APIInfoMgmt",
           "WSNMgmt",
           "AccountMgmt",
           "SystemMgmt",
           "ProcessMgmt"
        ]
     },
     "totalsize":5,
     "version":"1.0.0"
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/APIInfoMgmt/APIInfo
Example mosquito_sub -h <IP> -C 1 -t /APIInfoMgmt/<mac addr>/APIInfo

Retrieve available APIs.

Description Retrieve available APIs.
URI Resource Path /APIInfoMgmt/APIS
MQTT Topic Format N/A
Method(HTTP) GET
Request JSON Data N/A
Response JSON Data 
{  
  "apis":[  
     {  
        "uri":"/APIInfoMgmt/APIS"
     },
     {  
        "uri":"/APIInfoMgmt/APIInfo"
     },
     {  
        "uri":"/AccountMgmt/AccoutInfo"
     },
     {  
        "uri":"/AccountMgmt/AccoutConfig"
     },
     {  
        "uri":"/SystemMgmt/SystemInfo"
     },
     {  
        "uri":"/SystemMgmt/Action"
     },
     {  
        "uri":"/SystemMgmt/NetworkInfo"
     },
     {  
        "uri":"/SystemMgmt/NetworkConfig"
     },
     {  
        "uri":"/ProcessMgmt/Service"
     },
     {  
        "uri":"/ProcessMgmt/ServiceConfig"
     },
     {  
        "uri":"/ProcessMgmt/ServiceCtrl"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/Info"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/Info/reset"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/Setting"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/Setting/NetID"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/Setting/JoinKey"
     },
     {  
        "uri":"/WSNMgmt/IoTGW/WSN/00170d0000582cca/NetworkStatistics"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Action"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Action/AutoReport"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Info"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Info/Name"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Info/reset"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/Net"
     },
     {  
        "uri":"/WSNMgmt/00170d0000306265/SenHub/SenData"
     }
  ],
  "totalsize":24
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/APIInfoMgmt/APIS
Example MQTT N/A

Account Management Resources

Retrieve all accounts information.

Description Retrieve all accounts information.
URI Resource Path /AccountMgmt/AccountInfo
MQTT Topic Format /AccountMgmt/<mac addr>/AccountInfo
Method(HTTP/MQTT) GET/SUB
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "item":[  
        {  
           "username":"admin",
           "password":"$2a$10$2EXoFOQ6xsFZTguDwVWPaO63b17216uesj9TO6Phu/6Ci85DKqAte",
           "lastchange":"1463535734"
        }
     ],
     "totalsize":1
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/AccountMgmt/AccountInfo
Example mosquito_sub -h <IP> -C 1 -t /AccountMgmt/<mac addr>/AccountInfo
Item Description
totalsize Number of items in the result.
username Account name.
password Account password, but will not show real password.
lastchange Account last change time.

Change account password.

Description Change account password.
URI Resource Path /AccountMgmt /AccountConfig
MQTT Topic Format N/A
Method(HTTP) PUT
Request JSON Data 
{  
  "username":"admin",
  "password":"admin123"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X PUT -d '{"username":"admin","password":"admin123"}' http://username:password@<IP:Port>/restapi/AccountMgmt/AccountConfig
Example MQTT N/A

System Management Resources

Retrieve system information.

Description Retrieve system information.
URI Resource Path /SystemMgmt/SystemInfo
MQTT Topic Format /SystemMgmt/<mac addr>/SystemInfo
Method(HTTP/MQTT) GET/SUB
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "SystemInfo":{  
        "arch":"arm",
        "platform":"linux",
        "os":"Linux 3.10.17-1.0.2_ga",
        "systemtime":"2016-06-01 02:39:28",
        "uptime":"0 days,0 hours,30 minutes,30 seconds",
        "cpu":{  
           "cpuinfo":[  
              {  
                 "model":"ARMv7 Processor rev 10 (v7l)",
                 "speed":996
              },
              {  
                 "model":"ARMv7 Processor rev 10 (v7l)",
                 "speed":996
              }
           ],
           "totalsize":2
        },
        "cpuusage":{  
           "avgload":0.24,
           "currentload":6.9
        },
        "mem":{  
           "memsize":"1001.78 MB",
           "memusage":35.53
        },
        "swap":{  
           "swapsize":"0",
           "swapusage":0
        },
        "disk":{  
           "part":[  
              {  
                 "name":"/dev/root",
                 "mount":"/",
                 "size":"2.08 GB",
                 "usage":86.7
              },
              {  
                 "name":"/dev/mmcblk1p1",
                 "mount":"/media/mmcblk1p1",
                 "size":"7.98 MB",
                 "usage":62.78
              }
           ],
           "totalsize":2
        }
     }
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/SystemMgmt/SystemInfo
Example mosquito_sub -h <IP> -C 1 -t /SystemMgmt/<mac addr>/SystemInfo
Item Description
arch Device architecture.
platform Device OS Platform.
os Device OS version.
systemtime Device System time.
uptime Device uptime.
cpu Device CPU information.
cpuusage Device CPU usage.
memsize Device memory size.
memusage Device memory usage.
swapsize Device swap size.
swapusage Device swap usage.
disk.part Device disk partitions.
disk.part.name Device disk name.
disk.part.mount Device disk mount point.
disk.part.size Device disk size.
disk.part.usage Device disk usage.

Retrieve network information.

Description Retrieve network information.
URI Resource Path /SystemMgmt/NetworkInfo
MQTT Topic Format /SystemMgmt/<mac addr>/NetworkInfo
Method(HTTP/MQTT) GET/SUB
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "NetworkInfo":{  
        "hostname":"imx6qwise3310",
        "gateway":"172.22.15.254",
        "dns":{  
           "nameservers":[  
              {  
                 "nameserver":"172.22.2.100"
              },
              {  
                 "nameserver":"172.20.1.99"
              }
           ]
        },
        "iface":{  
           "lo":[  
              {  
                 "address":"127.0.0.1",
                 "netmask":"255.0.0.0",
                 "family":"IPv4",
                 "mac":"00:00:00:00:00:00"
              },
              {  
                 "address":"::1",
                 "netmask":"ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
                 "family":"IPv6",
                 "mac":"00:00:00:00:00:00"
              }
           ],
           "eth0":[  
              {  
                 "address":"172.22.12.20",
                 "netmask":"255.255.252.0",
                 "family":"IPv4",
                 "mac":"00:04:9f:01:11:11"
              },
              {  
                 "address":"fe80::204:9fff:fe01:1111",
                 "netmask":"ffff:ffff:ffff:ffff::",
                 "family":"IPv6",
                 "mac":"00:04:9f:01:11:11"
              }
           ],
           "eth0:0":[  
              {  
                 "address":"192.168.0.1",
                 "netmask":"255.255.255.0",
                 "family":"IPv4",
                 "mac":"00:00:00:00:00:00"
              }
           ]
        }
     }
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/SystemMgmt/NetworkInfo
Example mosquito_sub -h <IP> -C 1 -t /SystemMgmt/<mac addr>/NetworkInfo
Item Description
hostname Device Hostname.
gateway Device Default Gateway.
dns Name server setting.
iface Device Network Interface name.
address Device IP address.
netmask Device Netmask.
family IPv4 or IPV6.
mac Device MAC address.

Edit network settings.

Description Edit network settings.
URI Resource Path /SystemMgmt/NetworkConfig
MQTT Topic Format N/A
Method(HTTP) PUT
Request JSON Data 
{  
  "ipaddr":"172.22.12.38",
  "netmask":"255.255.252.0",
  "gateway":"172.22.12.1",
  "method":"static",
  "iface":"eth0"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X PUT -d '{"ipaddr":"172.22.12.38","netmask":"255.255.252.0"} "gateway":"172.22.12.1","method":"static","iface":"eth0"' http://username:password@<IP:Port>/restapi/SystemMgmt/NetworkConfig
Example MQTT N/A
Item Description
iface Device Network Interface name.
ipaddr Device IP address.
netmask Device Netmask.
gateway Device Default Gateway.
method DHCP or Static IP.

Set device "reboot" by action.

Description Set device "reboot" by action.
URI Resource Path /SystemMgmt/Action
MQTT Topic Format N/A
Method(HTTP) POST
Request JSON Data 
{  
  "action":"reboot",
  "value":1
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"action":"reboot","value":1}' http://username:password@<IP:Port>/restapi /SystemMgmt/Action
Example MQTT N/A
Item Description
action Determine action command.
value Determine action parameter.

Process Management Resources

Retrieve all services information.

Description Retrieve all services information.
URI Resource Path /ProcessMgmt/Service
MQTT Topic Format /ProcessMgmt/<mac addr>/Service
Method(HTTP/MQTT) GET/SUB
Request JSON Data N/A
Response JSON Data 
{  
  "result":{  
     "totalsize":27,
     "service":[  
        {  
           "name":"alljoyn",
           "onboot":0,
           "order":0
        },
        {  
           "name":"apmd",
           "onboot":1,
           "order":"20"
        },
        {  
           "name":"avahi-daemon",
           "onboot":1,
           "order":"21"
        },
        {  
           "name":"connman",
           "onboot":1,
           "order":"05"
        },
        {  
           "name":"crond",
           "onboot":1,
           "order":"90"
        },
        {  
           "name":"dbus-1",
           "onboot":1,
           "order":"02"
        },
        {  
           "name":"dustlink",
           "onboot":0,
           "order":0
        },
        {  
           "name":"hwclock.sh",
           "onboot":1,
           "order":"20"
        },
        {  
           "name":"mqtt",
           "onboot":1,
           "order":"96"
        },
        {  
           "name":"neard",
           "onboot":1,
           "order":"64"
        },
        {  
           "name":"nfsserver",
           "onboot":1,
           "order":"20"
        },
        {  
           "name":"ntpd",
           "onboot":1,
           "order":"20"
        },
        {  
           "name":"ofono",
           "onboot":1,
           "order":"22"
        },
        {  
           "name":"oprofileui-server",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"ppp",
           "onboot":0,
           "order":0
        },
        {  
           "name":"rc.local",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"rmnologin.sh",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"rpcbind",
           "onboot":0,
           "order":0
        },
        {  
           "name":"saagent",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"sawatchdog",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"serialmux",
           "onboot":0,
           "order":0
        },
        {  
           "name":"sshd",
           "onboot":1,
           "order":"09"
        },
        {  
           "name":"stop-bootlogd",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"syslog",
           "onboot":1,
           "order":"20"
        },
        {  
           "name":"tcf-agent",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"webmin",
           "onboot":1,
           "order":"99"
        },
        {  
           "name":"xinetd",
           "onboot":1,
           "order":"20"
        }
     ]
  }
}
Example curl -H "Content-Type: application/json" -X GET http://username:password@<IP:Port>/restapi/ProcessMgmt/Service
Example mosquito_sub -h <IP> -C 1 -t /ProcessMgmt/<mac addr>/Service
Item Description
totalsize Number of services in the result.
name Service name.
order Service startup order.
onboot Service on boot or not.

Edit service settings.

Description Edit service settings.
URI Resource Path /ProcessMgmt/ServiceConfig
MQTT Topic Format N/A
Method(HTTP) PUT
Request JSON Data 
{  
  "name":"xinetd",
  "order":20,
  "onboot":1
}
Response JSON Data 
{  
  "result":{  
     "name":"xinetd",
     "onboot":1,
     "order":20
  }
}
Example curl -H "Content-Type: application/json" -X PUT -d '{"name":"xinetd","order":20,"onboot":1}' http://username:password@<IP:Port>/restapi/ProcessMgmt/ServiceConfig
Example MQTT N/A

Start and Stop service.

Description Start and Stop service.
URI Resource Path /ProcessMgmt/ServiceCtrl
MQTT Topic Format N/A
Method(HTTP) POST
Request JSON Data 
{  
  "name":"xinetd",
  "action":"start"
}
Response JSON Data 
{
 "result":"true"
}
Example curl -H "Content-Type: application/json" -X POST -d '{"name":"xinetd","action":"start"}' http://username:password@<IP:Port>/restapi/ProcessMgmt/ServiceCtrl
Example MQTT N/A
Item Description
name Service name.
action Start or Stop service.
Retrieved from "https://ess-wiki.advantech.com.tw/wiki/index.php?title=IoTGateway/RESTful_APIv2&oldid=1928"