Gateway Management Solution Based on Intel® IoT Platform API Reference Manual August 2015
Document Number: 332845-001US
You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Intel products described herein. You agree to grant Intel a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Copies of documents which have an order number and are referenced in this document may be obtained by calling 1-800-548-4725 or by visiting: http://www.intel.com/design/literature.htm. Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Learn more at http://www.intel.com/ or from the OEM or retailer. No computer system can be absolutely secure. Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries. *Other names and brands may be claimed as the property of others. Copyright © 2015, Intel Corporation. All rights reserved.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 2
August 2015 Document Number: 332845-001US
Contents 1.0
Introduction ............................................................................................................................................ 5 1.1
2.0
Reference Documents ................................................................................................................................ 5
Definitions and Architecture ......................................................................................................... 6 2.1 2.2
Architecture ....................................................................................................................................................... 6 Communication Encryption ..................................................................................................................... 6
3.0
Device API Definition ........................................................................................................................ 7
4.0
Management API Definition ........................................................................................................ 21 4.1 4.2 4.3 4.4 4.5
5.0
User Management .......................................................................................................................................21 Project Information API...........................................................................................................................30 Device Information API ...........................................................................................................................37 Data Management API .............................................................................................................................54 Log Management API ................................................................................................................................65
Error Code Range ............................................................................................................................... 69
Appendix A ................................................................................................................................ API List
Tables Table Table Table Table Table Table Table Table Table Table Table Table Table Table Table Table
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.
Reference Documents ................................................................................................................................ 5 Control APIs in REST Paths .................................................................................................................... 7 Control API Interface Details ................................................................................................................. 8 Use Roles...........................................................................................................................................................21 User Management API in Restful Paths ........................................................................................21 User Management API Details ............................................................................................................22 Project Information Management API ...........................................................................................31 Project Information Management API Details .........................................................................31 Device Information Management API ...........................................................................................37 Device Management API Details .......................................................................................................38 Data Management API .............................................................................................................................54 Data Management API Details............................................................................................................55 Log Management APIs .............................................................................................................................65 Log Management API Details ..............................................................................................................66 Error Code Ranges ......................................................................................................................................69 API List................................................................................................................................................................70
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 3
70
Revision History Date
Revision
August 2015
1.0
Description Initial release.
§
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 4
August 2015 Document Number: 332845-001US
Introduction
1.0
Introduction This document defines the Application Programming Interface (API) between the cloud backend and the frontend management interface. In addition to the platform management portal, the frontend also includes system like data visualization. The document also defines the communication requirements between backend of the system and gateway device.
1.1 Table 1.
Reference Documents Reference Documents Document
Document No./Location
The JSON Data Interchange Standard
ECMA-404
§
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 5
Definitions and Architecture
2.0
Definitions and Architecture
2.1
Architecture In the system, the API system acts as the backend that exports functions by HTTP POST invocation. The frontend is a UI module that handles all human interactions. MQTT Broker is adopted for the communication between the backend system and the edge gateways. The API calls for the edge gateways are named device APIs. The API calls for platform and data management are named management APIs. These two categories of APIs bridge the frontend systems and the backend.
2.2
Communication Encryption The API includes the authentication for user messages. However, it is required to adopt the transportation layer encryption for additional security. The API can be wrapped as a JAVA class interface. §
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 6
August 2015 Document Number: 332845-001US
Device API Definition
3.0
Device API Definition The device APIs include two categories of APIs: One is the control API for gateways via the MQTT broker, and the other is the data APIs for gateway submitting data and other information. The frontend management portal can call the control APIs to manage individual gateway device. The control APIs are applied to the gateway device even though they are proxied by the MQTT Broker. Such APIs include operations to the gateway configuration, applications, and base platform. Because control APIs need to be transmitted over the network, executed by the gateway, and then collected the returned value, there are uncontrollable latency on the network and variance in gateway execution time. Thus control APIs are all defined as bi-stage APIs, where the stage-1 API call returns an API query code and its timeout value if successful accepted. The caller has to call the API status query API (getAPIStatus as the stage-2 API call) with the query code after the timeout value to obtain the control API return value. If the API has not finished execution, a new API query code and timeout value is returned for the next status query. The following are the control APIs in REST paths.
Table 2.
Control APIs in REST Paths Index
API Method and Path
Functionality
A.1
POST dev/ctl/getVer
Get gateway version.
A.2
POST dev/ctl/getcfg
Get gateway configuration.
A.3
POST dev/ctl/setcfg
Set gateway configuration.
A.4
POST dev/ctl/ping
Get the gateway online status.
A.5
POST dev/ctl/updatefirmware
Update gateway firmware.
A.6
POST dev/ctl/system
Execute customized system command
A.7
POST dev/ctl/getapplist
Get list of applications on gateway
A.8
POST dev/ctl/startapp
Start one application
A.9
POST dev/ctl/stopapp
Stop one application
A.10
POST dev/ctl/installapp
Install one application
A.11
POST dev/ctl/reboot
Restart the gateway
A.12
POST dev/ctl/filec2d
Transfer a file from cloud to device
A.13
POST dev/ctl/filed2c
Transfer a file from device to cloud
A.14
POST dev/ctl/rpccall
Call device RPC
A.15
POST dev/ctl/getapistatus
Get API execution status
August 2015 Document Number: 332845-001US
Priority
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 7
Device API Definition
Index
API Method and Path
Functionality
Priority
A.16
POST dev/ctl/listcfg
List gateway configuration
A.17
POST dev/ctl/preparelog
Gateway put log into a local file
A.18
POST dev/ctl/filestats
Return information of local file
The following are the API interface details in JAVA language syntax. Both parameters and return values are defined as JSON message. Table 3.
Control API Interface Details Index
API Details
Note
A.15
String getAPIstatus(String json_str); Functionality: get API execution result. Params：JSON data structure { “method”:”dev/ctl/getapistatus”, “api_qid”:”QID”, //ASCII query code from the stage-1 control API call. “auth_token”:”xxx” //token to represent the calling user. } Return value is also JSON message. If the API completes execution, { “retcode”:”0”,
//API return code, 0 if successful，
//code >10000 indicates errors ……
// Json structure varies based on API.
} If the stage-1 control API is still executing, { “retcode”:”1”, “api_qid”:”QID”,
//API in progress code == 1. //API query ID (QID),
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 8
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
“time_out”:”100”,
//Timeout value in millisecond.
} A.1
String getVer(String json_str); Params: JSON string { “method”:”dev/ctl/getVer”, “device”:”id”, //device ID that uniquely identifying the gateway // in format of “/dev/ctl/[project_id]/[gateway_id]/” // in which project_id is defined by project API, // gateway_id is returned by gateway mngt API, // both are ASCII strings. “auth_token”:”xxx” } Return: JSON STRING { “retcode”: “1”,
//Return 1 if successful, otherwise >10000
“api_qid”:”QID”;
//ASCII API QID
“timeout”:”1000”; //Timeout value in milliseconds. } getAPIStatus returns the following JSON structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
"ver": “1.0”
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 9
Device API Definition
Index
API Details
Note
}
A.2
String getCfg(String json_str); Params: { “method”:”dev/ctl/getcfg”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “path”:”config_path”, //the path that maps to a module/app. “name”:”config_name” //the name of the configuration entry. } Return: Same as getVer(); getAPIStatus() returns the following JSON structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“value”:value //the value of the config.(int/string/json) } A.3
String setCfg(String json_str); Params: { “method”:”dev/ctl/setcfg”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “path”:”config_path”, //the path that maps to a module/app.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 10
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
“name”:”config_name”, //the name of the configuration entry. “value”:value
//the new value of the configuration entry.
} Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
} A.4
String Ping(String json_str); Params: { “method”:”dev/ctl/ping”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx” } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”pong” } A.5
String updateFirmware(String json_str); Params: {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 11
Device API Definition
Index
API Details
Note
“method”:”dev/ctl/updatefirmware”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “srcaddr”:”url”, // firmware address, remotely or locally. “version”:”1.1” // New firmware version. } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”Execution result” } A.6
String system(String json_str); Params: { “method”:”dev/ctl/system”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “cmd”:”system cmd” //the command to be executed } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 12
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
“data”:”Execution result” //ASCII string. } A.7
String getAppList(String json_str); Params: { “method”:”dev/ctl/getapplist”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx” } Return: Same as getVer(). getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“apps”:{ { “appname”: “appname”, ”version”:”1.0”, “status”:”running”} , { “appname”: “appname”, ”version”:”1.0”, “status”:”stopped”} } } A.8
String startApp(String json_str); Params: { “method”:”dev/ctl/startapp”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”,
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 13
Device API Definition
Index
API Details
Note
“name”:”appname”,
// APP name with full path
“params”:”parameter list”, // App params encoded in base64 } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”Execution result” //ASCII string. } A.9
String stopApp(String json_str); Params: { “method”:”dev/ctl/stopapp”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “name”:”appname” // Name of the app } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”Execution result” //ASCII string. } A.10
String installApp(String json_str);
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 14
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
Params: { “method”:”dev/ctl/installapp”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “apppath”:”url” // Location of the app. } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”Execution result” } A.11
String reboot(String json_str); Params: { “method”:”dev/ctl/reboot”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx” } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
August 2015 Document Number: 332845-001US
// 0 if successful, or >10000 in case of errors.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 15
Device API Definition
Index
API Details
Note
“data”:”Execution result” } A.12
String fileC2D(String json_str); Params: { “method”:”dev/ctl/filec2d”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “src”:”path_name or filecontent” //base64 format, 512KB max. “dest”:”path_name” // destination in the gateway file system. } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”,
// 0 if successful, or >10000 in case of errors.
“data”:”Execution result” } A.13
String fileD2C(String json_str); Params: { “method”:”dev/ctl/filed2c”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “src”:”path_name” // the device file path.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 16
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
“dest”:”path_name” // cloud URL (currently unused). } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode":”0”, “data”:”File content” //base64 format } A.14
String rpcCall(String json_ptr); Params: { “method”:”dev/ctl/rpccall”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “cmd”:“string” // the RPC information. } The cmd consists of three components, “path”, “method”, and json code, separated by one “space” character. If the json code has space characters, they are still treats as part of the json code component. Example of json code includes (one line is one example): “abc” 1.234 {“abc”:1}
deviceSame as getVer(); Return: Same as getVer();
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 17
Device API Definition
Index
API Details
Note
getAPIStatus returns the following JSON structure: { “retcode":”0”, “data”:”Execution result” } A.16
String listCfg(String json_str); Params: { “method”:”dev/ctl/listcfg”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “path”:”config_path”, //path that maps to a module/app, could be “*” } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“configs”:[ //the list of the config. {“path”:path, “name”:name, “data_type”:type, “description”:value} {“path”:path, “name”:name, “data_type”:type, “description”:value} {“path”:path, “name”:name, “data_type”:type, “description”:value} ] } A.17
String prepareLog(String json_str);
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 18
August 2015 Document Number: 332845-001US
Device API Definition
Index
API Details
Note
Params: { “method”:”dev/ctl/preparelog”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”, “time_from”:”time”, “time_to”:”time”, “tag”:value
// start time in epoch time (float format) // end time in epoch time (float format)
// tag filter, could be “*”
} Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“name”:”filename”,
// the path and name of the file.
“compress”:protocol, //compress method of the file, // support “bz2”, “gz”, “none”. “size”:size
//file size after compression.
} A.18
String fileStats(String json_str); Params: { “method”:”dev/ctl/filestats”, “device”:”id”,
// For format, refer A.1.
“auth_token”:”xxx”,
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 19
Device API Definition
Index
API Details
Note
"filename": “filename”, } Return: Same as getVer(); getAPIStatus returns the following JSON structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“size”:filesize
// size of the file.
}
§
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 20
August 2015 Document Number: 332845-001US
Management API Definition
4.0
Management API Definition For security, all management APIs require user authentication. All access to the cloud platforms should present an “auth_token”. The system and project administrator obtain the token with a password, and the API user gets the token via public key based authentication. The token is used in all API calls to the backend, until it is expired or removed by the logout API. Management APIs also use JSON as the format for parameters and return values. Because management APIs happen between cloud backend and the web front with limited latency, bi-stage is not used here.
4.1
User Management The cloud management platform defines a number of use roles.
Table 4.
Use Roles User Type
Role Descriptions
System admin
Super user, read/write to all data. Key functions are creating projects, adding project admin accounts, and access platform logs.
Project admin
The main operator of the project management: maintaining project information and associated metadata; device control; query and export data and events.
API user
Limited access right: read the metadata from project; access stats, raw data, and alert/event logs.
User management includes creating and modifying user information, together with user authentication and session management. Table 5.
User Management API in Restful Paths Index
API Method and Path
Functionality
1.1
POST admin/user/adduser
Add user with certain roles.
1.2
POST admin/user/updateuser
Modify user information
1.3
POST admin/user/getusrinfo
Get user information
August 2015 Document Number: 332845-001US
Priority
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 21
Management API Definition
Index
API Method and Path
Functionality
Priority
1.4
POST admin/user/setpass
Set user password
1.5a
POST admin/user/userlogin1
The login interface for all users.
1.5b
POST admin/user/userlogin2
User login with password
1.6
POST admin/user/userlogout
The login interface for all users.
1.7
POST admin/tokens/listtokens
List all active tokens.
2
1.8
POST admin/tokens/deltoken
Delete one token
2
1.9
POST admin/user/setapikey
Set the public key for API user
1.10
POST admin/user/apilogin2
API user login with keys
The following are the API details in JAVA language syntax. Table 6.
User Management API Details Index
API Details
Note
1.1
String addUser(String json_str); Params: Json_str string (auth_token and username are required): { “method”:”admin/user/adduser”, “auth_token”:”token”, //User token obtained via login API. “username”:”user_name”, “role”:”project_id,admin”, //or“project_id,api”, //“system,admin” (require platform privilege) }
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 22
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
Return: { “retcode”:”0” // 0 if successful, or >10000 in case of errors. } 1.2
String updateUser(String json_str); Params: Json_str string (auth_token and username are required): { “method”:”admin/user/updateuser”, “auth_token”:”token”,
//User token.
“username”:”user_name”, “role”:”system,admin”, // or ”project_id,admin”, “project_id,api”, // “project_id,ops” (currently unused) “active”：”true”
// whether the user account is activated.
} Return: { “retcode”:”0” // 0 if successful, or >10000 in case of errors. } 1.3
String getUserInfo(String json_str); Params: { “method”:”admin/user/getuserinfo”, “auth_token”:”sid”,
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 23
Management API Definition
Index
API Details
Note
“username”:”user_name”, } Return: no password will be returned. { “username”:”user_name”, “role”:”system,admin”, “createtime”:time, “updatetime”:time,
// epoch time, float format.
“active”：”true” } 1.4
String setPass(String json_str); Params: { “method”:”admin/user/setpass”, “auth_token”:”sid”, // User token, or token of admins “algorithm”:”SHA256”, //Currently SHA256, may add other algorithms later. “username”:”user_name”， “passhash”:”user_password” // submit the password, so SSL is required // this is for server to check strength. } Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 24
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
} 1.5a
String userLogin1(String json_str); Params: { “method”:”admin/user/userlogin1”, “username”:”user_name”, } Return: { “retcode”:”0”, “login_id”:”xxx”,
// login id representing this login request，
//can contain all login information //so server can be stateless. “allowed_ops”:”pass”, //Allowed next step process //”pass” for password login, use userlogin2 //”key” for key-based login, use apilogin2 “algorithm”:” SHA256”,
//Algorithm is SHA256
//or RSA (pub/prv) “challenge”:”xxx”,
//challenge string, only for “key” mode.
"alternatives": [...] // All possible methods. } 1.5b
String userLogin2(String json_str); Params: {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 25
Management API Definition
Index
API Details
Note
“method”:”admin/user/userlogin2”, “login_id”:”xxx”,
// login id generated by the server
“response”:”xxx”
//Hash value calculated with user password.
} Return: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“auth_token”:”xxx” // user token to be used in later API calls. } 1.6
String userLogout(String json_str); Params: { “method”:”admin/user/userlogout”, “auth_token”:”xxx” } Return: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
} 1.7
String listTokens(String json_str); Params: { “method”:”admin/tokens/listtokens”, “auth_token”:”xxx”
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 26
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
} Return: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“sessions”:[ {“auth_token”:”xxx”, “uname”:”name”, “ip”:user_ip, “time”:”lasttime”} {“auth_token”:”xxx”, “uname”:”name”, “ip”:user_ip, “time”:”lasttime”} {“auth_token”:”xxx”, “uname”:”name”, “ip”:user_ip, “time”:”lasttime”} ] } 1.8
String delToken(String json_str); Params: { “method”:”admin/tokens/deltoken”, “auth_token”:”xxx”, “delete_token”:”xxx”
//token to be deleted.
} Return: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
} 1.9
String setApiKey(String json_str); Params: {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 27
Management API Definition
Index
API Details
Note
“method”:”admin/user/setapikey”, “auth_token”:”sid”, // User token, or token of admins “algorithm”:”RSA”, // currently only support RSA. “username”:”user_name”, “userkey”:”public_key” // Public key of the user, prv key is kept by user // Prv key should never be transmitted. } Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
} 1.10
String apiLogin2(String json_str); Params: { “method”:”admin/user/apilogin2”, “login_id”:”xxx”, “response”:”xxx” “crand”: “xxx”
// login id representing this login request //Signature of the login_id with user prv key. // A client generated random string,
// less than 256 char in length. } Return: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“auth_token”:”xxx” // user token to be used in later API calls. Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 28
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
} Login process example: 1） When a user inputs username and password on the web page, the web page calls POST /v1/admin/user/userLogin1 HTTP/1.1 Content-type: text/plain Host: localhost { “username”: “root”, } 2） Server encodes the information of the Login, such as user_name, ip, and time, into the login id, and returns it HTTP/1.1 200 OK Content-type: text/plain { “retcode”: 0, “login_id”: “ajldfjsadgjowierjoiwerowiejrsjlkjlkdjglksdjflsdf”, “allowed_ops”:”PASS” “algorithm”:”SHA256”, } 3） The algorithm can be the following: SHA256(user_password)
POST /v1/admin/user/userLogin2 HTTP/1.1 Content-type: text/plain Host: localhost
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 29
Management API Definition
{ “login_id”: “ajldfjsadgjowierjoiwerowiejrsjlkjlkdjglksdjflsdf”, “response”:”xxx” } 4） The server uses the information in the login_id to verify the correctness of the response. If correct, generate an auth_token for the user. The auth_token could contain user role, time, user IP, or server signature. HTTP/1.1 200 OK Content-type: text/plain { “retcode”: 0, “auth_token”: “ajl9079wierjoiwerowiejrsjlkjlkdjglksdjflsdf”, } For API login, the response is the following: Sign_SHA256_RSA(privateKey, username+challenge+crand) For example, if the username is “api0123”, the challenge from server is “abcdef”, the client randomly generates “9876”, and the response is verified by the following: String message = “api0123abcdef9876”; Signature sign = Signature.getInstance("SHA256WithRSA"); sign.initVerify(publicKey); sign.update(message.getBytes()); sign.verify(response);
4.2
Project Information API The project information management API manages project information and the status of gateways in this project.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 30
August 2015 Document Number: 332845-001US
Management API Definition
Table 7.
Project Information Management API Index
API Method and Path
Functionality
Priority
2.1
POST admin/project/addproject
Create a new project (platform admin only)
2.2
POST admin/project/updateproject
Update project information
2.3
POST admin/project/getprojectinfo
Get project information.
2.4
POST admin/project/deleteproject
Delete a project (platform admin only)
2.5
POST admin/project/listprojects
List all projects in the platform
2.6
POST admin/project/listdevinproject
List matched device in a project
2.7
POST admin/project/getprojectstats
Return project stats data.
2
2.8
POST admin/project/listprojectusers
List all users in a project
2
The following are the API details in JAVA language syntax. Table 8.
Project Information Management API Details Index
API Details
Note
2.1
String addProject(String json_str); Params: Json_str structure: { “method”:”admin/project/addproject”, “auth_token”:”token”,
// User token
“name”:”project name”, // Name of the project “vendor”:”vendor name”, // Vendor name
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 31
Management API Definition
Index
API Details
Note
“info”:”project information”, //Short description of the project “tag”:”test, energy”,
//Project tags.
} Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
“project_id”:”id” // Project ID assigned by the system } 2.2
String updateProject(String json_str); Params: Json_str structure: (token and project_id are required, the others are options, and note that “vendor” field cannot be changed) { “method”:”admin/project/updateproject”, “auth_token”:”token”, “project_id”:”id”,
// User token
// Project ID assigned by the system
“name”:”project name”, // Name of the project “info”:”project information”, // Short description of the project “tag”:”test, energy”,
//Project tags
} Return: { “retcode”:”0” // 0 if successful, or >10000 in case of errors. } 2.3
String getProjectInfo(String json_str);
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 32
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
Params: Json_str structure: { “method”:”admin/project/getprojectinfo”, “auth_token”:”xxx”, “project_id”:”id” // Project ID assigned by the system } Return: Json_str structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“project_id”:”id”,
// ASCII string
“name”:”project name”, // Name of the project “vendor”:”vendor name”, “info”:”project information”, “createtime”:”time”, number)
//Project creation time in epoch (float
“updatetime”:”time”, //Project update time in epoch (float number) “tag”:”test, energy” } 2.4
String deleteProject (String json_str); Params: Json_str structure: {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 33
Management API Definition
Index
API Details
Note
“method”:”admin/project/deleteproject”, “auth_token”:”xxx”, “project_id”:”id” // Project ID assigned by the system } Return: Json_str structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
} 2.5
String listProjects (String json_str); Params: Json_str structure: { “method”:”admin/project/listprojects”, “auth_token”:”xxx” } Return: Json_str structure: { “retcode”:”0”, “projects”:[
// 0 if successful, or >10000 in case of errors. // Deleted projects are not included.
{“id”:”id1”, “name”:”project1” }, {“id”:”id2”, “name”:”project2” }, {“id”:”id3”, “name”:”project3” }
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 34
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
] } 2.6
String listDevinProject (String json_str); Params: Json_str structure: { “method”:”admin/project/listdevinproject”, “auth_token”:”xxx”, “project_id”:”id”, // Project ID assigned by the system “filter”:””,
//Device filters, currently is empty to match all.
} Return: Json_str structure: { “retcode”:”0”, “total”:100,
// 0 if successful, or >10000 in case of errors. // Number of devices matched and returned.
“gateways”: [ { “gateway_id”:id, “name”:gw_name, “status”:status}, { “gateway_id”:id, “name”:gw_name, “status”:status}, { “gateway_id”:id, “name”:gw_name, “status”:status} ] } 2.7
String getProjectStats(String json_str);
TBD
Params:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 35
Management API Definition
Index
API Details
Note
Json_str structure: { “method”:”admin/project/getprojectstats”, “auth_token”:”xxx”, “project_id”:”id” // Project ID assigned by the system } Return: Json_str structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“activedevcounts”:100, // The number of active devices. “offlinedevcounts”:100, // the number of offline devices. “alarmstarttime”: time, // UTC time where alarmcounts start. “alarmcounts”:[“n1”, “n2”, “n3”, …, “n72”] //number of alarms in each hour. // hours are UTC time for 0:00 clock from two // days ago to 24:00 today. // For remaining hours today, these numbers // will be 0. “stats”:””
//other stats.
} 2.8
String listProjectUsers(String json_str); Params: Json_str structure:
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 36
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
{ “method”:”admin/project/listprojectusers”, “auth_token”:”xxx”, “project_id”:”id” // Project ID assigned by the system } Return: Json_str structure: { “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“users”:[ {“username”:name, “role”:”project_id,admin”}, {“username”:name, “role”:”project_id,ops”}, {“username”:name, “role”:”project_id,api”} ] }
4.3
Device Information API The device information management API maintains the information (metadata) about devices, such as device information, the data points in a device, and the groups in the project.
Table 9.
Device Information Management API Index
API Method and Path
Functionality
3.1
POST admin/dev/adddev
Add a new device entry.
3.2
POST admin/dev/updatedev
Update device information.
August 2015 Document Number: 332845-001US
Priority
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 37
Management API Definition
Index
API Method and Path
Functionality
3.3
POST admin/dev/getdevinfo
Get device information.
3.4
POST admin/dev/deletedev
Delete a device entry.
3.5
POST admin/dev/adddatapoint
Add a data point to a device
3.6
POST admin/dev/updatedatapoint
Remove data point from device
3.7
POST admin/dev/deletedatapoint
Update data point information
3.8
POST admin/dev/getdatapointinfo
Get data point information
3.9
POST admin/dev/listdatapoints
List data point in a project
3.10
POST admin/group/addgroup
Add a group in this project.
3.11
POST admin/group/updategroup
Update group information
3.12
POST admin/group/getgroupinfo
Get group information
3.13
POST admin/group/deletegroup
Delete a group.
3.14
POST admin/group/listgroups
List groups in the project.
3.15
POST admin/project/listdevbygroup
List devices by group
3.16
POST admin/dev/listdatapointbygroup
List data point by group
3.17
POST admin/group/listgrouppath
List hierarchy path of a group
3.18
POST admin/dev/getdevkey
Get the device key of a device
Priority
2
The following are the API details in JAVA language syntax. Table 10. Device Management API Details Index
API Details
3.1
String addDev(String json_str);
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 38
Note
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
Params: Json_str structure: { “method”:”admin/dev/adddev”, “auth_token”:”token”, “project_id”:”id”, “device_hw_id”:”id”,
// User token
// Project ID. // Hardware ID of a device, can be its
//serial number or MAC address. “tag”:”china, rockontrol”, //Device tags “name”:”device name”, //Name of the device. “vendor”:”intel”,
// Device vendor.
“systeminfo”:”x86, linux”, // Software system information of the device “groupids”:[id1, id2],
// Group IDs this device is associated with
“location”:”address”
// User defined location information
// Recommendations: lng:110.2,lat: 48.1 // or gcj02:xxxx // or bd09ll:xxxx // or addrd: 100 Main street, Beijing } Return: { “retcode”:”0” // 0 if successful, or >10000 in case of errors. “gateway_id”:”id”,
// the device ID assigned to this device
}
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 39
Management API Definition
Index
API Details
Note
3.2
String updateDev(String json_str); Params: Json_str structure: token, project_id, and gateway_id are required. { “method”:”admin/dev/updatedev”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID.
“gateway_id”:”id”,
// Device ID
“device_hw_id”:”id”,
// the following are the same as the ones in
// AddDev API. “tag”:”china, rockontrol”, “name”:”device name”, “vendor”:”intel”, “systeminfo”:”x86, linux”, “groupids”:[id1, id2], “location”:”address”, } Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
} 3.3
String getDevInfo(String json_str); Params: Json_str structure:
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 40
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
{ “method”:”admin/dev/getdevinfo”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“gateway_id”:”id”,
// Device ID
} Return: Json_str structure: { “retcode”:”0”, “project_id”:”id”,
// Project ID
“gateway_id”:”id”,
// Device ID
“device_hw_id”:”id”,
// the following are the same as the ones in
// AddDev API. “tag”:”china, rockontrol”, “name”:”device name”, “vendor”:”intel”, “systeminfo”:”x86, linux”, “groupids”:[id1, id2], “location”:”address”, “createtime”:time, “updatetime”:”time”,
// Device creation time from epoch (float) //Device update time from epoch (float)
} 3.4
String deleteDev(String json_str);
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 41
Management API Definition
Index
API Details
Note
Params: Json_str structure: { “method”:”admin/dev/deletedev”, “auth_token”:”token”,
// User token
“project_id”:”id”, “gateway_id”:”id”, } Return: Json_str structure: { “retcode”:”0” } 3.5
String addDataPoint(String json_str); Params: Json_str structure: { “method”:”admin/dev/adddatapoint”, “auth_token”:”token”,
// User token
“project_id”:”id”, “gateway_id”:”id”, “name”:”datapoint”, “datatype”:”float”, “dataunit”:”kw”,
// Name of the data point // Data type of this data point // Data unit, could be the following
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 42
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
// Kwh/raw Kilowatt hour // Va/raw
A phase voltage
// Vb/raw
B phase voltage
// Vc/raw
C phase voltage
// activePower/raw Active power // Celsius/raw Temperature // t/raw
Ton
// Kpa/raw
Pressure
// m3/raw
Current
“description”:”default”, // User defined description “groupid”:[group_id1,…] // Groups the data point is associated with “tag”:””
// Data point tags
“userdata”:url,
// User data, could be URL
} Return: Json_str structure: { “retcode”:”0”, “datapoint_id”:”id”
// Platform assigned data point ID.
} 3.6
String updateDataPoint(String json_str); Params: Json_str structure: token,project_id,gateway_id, datapoint_id are required. {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 43
Management API Definition
Index
API Details
Note
“method”:”admin/dev/updatedatapoint”, “auth_token”:”token”,
// User token
“project_id”:”id”, “gateway_id”:”id”, “datapoint_id”:”id”
// Data point ID
“name”:”datapoint”,
// The following are the same as the ones
// in AddDataPoint API. “datatype”:”float”, “dataunit”:”kw”, “description”:”default”, “groupid”:[group_id1, ] “tag”:””, “userdata”:url, } Return: Json_str structure: { “retcode”:”0” } 3.7
String deleteDataPoint(String json_str); Params: Json_str structure: { “method”:”admin/dev/deletedatapoint”,
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 44
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
“auth_token”:”token”,
Note
// User token
“project_id”:”id”, “gateway_id”:”id”, “datapoint_id”:”id”,
// Data point ID
} Return: Json_str structure: { “retcode”:”0” } 3.8
String getDataPointInfo(String json_str); Params: Json_str structure: token,project_id,gateway_id, datapoint_id are required { “method”:”admin/dev/getdatapointinfo”, “auth_token”:”token”,
// User token
“project_id”:”id”, “gateway_id”:”id”, “datapoint_id”:”id”
// Data point ID
} Return: Json_str structure: { “retcode”:”0”,
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 45
Management API Definition
Index
API Details
Note
“datapoint_id”:”id”
// Data point ID
“name”:”Temperature 1”, // Name of the data point “datatype”:”float”,
// The following are the same as the ones
// in AddDataPoint API. “dataunit”:”kw”, “description”:”default”, “tag”:””, “userdata”:url, “groupid”:[group_id1,] “createtime”:time,
// Data point creation time in epoch (float)
“updatetime”:time,
// Data point update time in epoch (float)
“deleted”:false
// whether data point has been deleted.
} 3.9
String listDataPoints(String json_str); Params: Json_str structure: { “method”:”admin/dev/listdatapoints”, “auth_token”:”xxx”, “project_id”:”id”, // Project ID assigned by the system “gateway_id”:”id”,
// Device ID, could be * for wild card
} Return: Json_str structure: Deleted data points will not be included.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 46
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
{ “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“datapoints”: [ {“gateway_id”:gid, “id”: id1, “name”:name1, “userdata”:userdata }, {“gateway_id”:gid, “id”: id2, “name”:name2, “userdata”:userdata }, {“gateway_id”:gid, “id”: id3, “name”:name3, “userdata”:userdata } ] } 3.10
String addGroup(String json_str); Params: Json_str structure: { “method”:”admin/group/addgroup”, “auth_token”:”token”, “project_id”:”id”,
// User token
// Project ID
“name”:”South Bldg 1”, // Group name, can also be “meter 1” “type”:”zone”,
// Group type, only two types “zone”,”meter”.
“parentgroupid”:”groupid”, // Parent group, 0 if empty. // parent group must share the same type “descriptions”:”Building”, // Description of the group. “userdata”:”customized”, // User defined data, such as barcode. “tags”:”meters, dev”
// User defined tags
} Return:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 47
Management API Definition
Index
API Details
Note
{ “retcode”:”0”,
// 0 if successful, or >10000 in case of errors.
“group_id”:”id”
// Platform assigned group ID
} 3.11
String updateGroup(String json_str); Params: Json_str structure: token, project_id, gateway_id are required. { “method”:”admin/group/updategroup”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“group_id”:”id”,
// Group ID
“name”:”South Bldg 1”, // The following are the same as the ones // defined in AddGroup API. “type”:”zone”, “parentgroupid”:”groupid”, “descriptions”:”Building”, “userdata”:”customized”, “tags”:”meters, dev” } Return: { “retcode”:”0” // 0 if successful, or >10000 in case of errors. }
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 48
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
3.12
String getGroupInfo(String json_str); Params: Json_str structure: { “method”:”admin/group/getgroupinfo”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“group_id”:”id”,
// Group ID
} Return: Json_str structure: { “retcode”:”0”, “project_id”:”id”,
// Project ID
“group_id”:”id”,
// Group ID
“name”:”South Bldg 1”, // The following are the same as the ones // defined in AddGroup API. “type”:”zone”, “parentgroupid”:”groupid”, “descriptions”:”Building”, “userdata”:”customized”, “tags”:”meters, dev” “childrengroupids”:[id1, id2], // Groups belong to this group． // read-only, updated by the system.
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 49
Management API Definition
Index
API Details
Note
“createtime”:time,
// Group creation time in epoch (float)
“updatetime”:”time”,
// Group update time in epoch (float)
} 3.13
String deleteGroup(String json_str); Params: Json_str structure: { “method”:”admin/group/deletegroup”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“group_id”:”id”,
// Group ID
} Return: Json_str structure: { “retcode”:”0” } 3.14
String listGroups(String json_str); Params: Json_str structure: { “method”:”admin/group/listgroups”, “auth_token”:”token”, “project_id”:”id”,
// User token
// Project ID
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 50
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
“group_id”:”id1”, “type”:”meter”,
// List all groups related to id1, * for wild card // Group type, * for wild card
} Return: Json_str structure: { “retcode”:”0”, “groups”:[ {“id”:”id1”, “name”:”name1”, “type”:”zone”, “parentid”:”0”}, {“id”:”id2”, “name”:”name1”, “type”:”zone”, “parentid”:”id1”}, {“id”:”id3”, “name”:”name1”, “type”:”zone”, “parentid”:”id1”} ] } 3.15
String listDevByGroup(String json_str); Params: Json_str structure: { “method”:”admin/project/listdevbygroup”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“group_id”:”id1”,
// List device in id1 including child groups.
// only applicable to “zone” groups. } Return:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 51
Management API Definition
Index
API Details
Note
Json_str structure: { “retcode”:”0”, “gateways”:[ { “gateway_id”:id, “name”:gw_name, “status”:status}, { “gateway_id”:id, “name”:gw_name, “status”:status}, { “gateway_id”:id, “name”:gw_name, “status”:status} ] } 3.16
String listDataPointByGroup(String json_str); Params: Json_str structure: { “method”:”admin/dev/listdatapointbygroup”, “auth_token”:”token”,
// User token
“project_id”:”id”,
// Project ID
“group_id”:”id1”,
// List all the datapoints in group id1.
} Return: Json_str structure: { “retcode”:”0”, “datapoints”: [ {“gateway_id”:gid, “id”: id1, “name”:name1, “userdata”:userdata},
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 52
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
{“gateway_id”:gid, “id”: id2, “name”:name2, “userdata”:userdata }, {“gateway_id”:gid, “id”: id3, “name”:name3, “userdata”:userdata } ] } 3.17
String listGroupPath(String json_str); Params: Json_str structure: { “method”:”admin/group/listgrouppath”, “auth_token”:”token”, “project_id”:”id”, “group_id”:”gid1”,
// User token
// Project ID // the start group ID
} Return: Json_str structure: { “retcode”:”0”, “path”: [ {“id”: gid1, “name”:name1 }, {“id”: parentid1, “name”:name2 }, {“id”: grandparentid2, “name”:name3 }, {“id”: rootid, “name”:rootname } ] }
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 53
Management API Definition
Index
API Details
Note
3.18
String getDevKey(String json_str); Params: Json_str structure: { “method”:”admin/dev/getdevkey”, “auth_token”:”token”, “project_id”:”id”,
// User token
// Project ID
“gateway_id”:”dev1”,
// Device ID
} Return: Json_str structure: { “retcode”:”0”, “devkey”:”xxx”
// Device key, could be 256 AES key.
}
4.4
Data Management API The data management APIs provide the interface to query and export data. The data could be raw data collected from sensor, or aggregated statistics data (stats data). Stats data can be based on data from a number of data points from the same or different devices. This set of API also includes the management of stats data metadata. Because the export data calls may take time to complete, they are implemented as bi-stage APIs.
Table 11. Data Management API Index
API Method and Path
Functionality
4.1
POST data/rawdataquery
Query raw data by filters.
4.2
POST data/rawdataexport
Export raw data.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 54
Priority
2
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Method and Path
Functionality
Priority
4.3
POST data/getexportstatus
Get the data export status.
4.4
POST data/statsdataquery
Query stats data by rules.
2
4.5
POST data/statsdataexport
Export stats data.
2
4.6
POST data/alarmdataquery
Query alarm data.
4.7
POST data/alarmdataexport
Export alarm data.
2
4.8
POST alm/pollalarm
Poll alarm.
2
The following are the API details in JAVA language syntax. Table 12. Data Management API Details Index
API Details
Note
4.1
String rawDataQuery(String json_str); Params: Json_str structure: { “method”:”data/rawdataquery”, “auth_token”:”token”,
// User token
“maxdatapoints”:”1000”, // Max number of data point to be returned, // 0 means unlimited. “time_from”:”time”,
// start time in epoch time (float format)
“time_to”:”time”,
// end time in epoch time (float format)
“project_id”:”id1”,
// Project filter, based on id.
“gateway_id”: “*”,
// Gateway ID filter, * for wild card
“datapoint_id”:”*”,
// Datapoint ID filter, * for wild card
“skip”:”100”,
August 2015 Document Number: 332845-001US
// Skip the first N number of record in result
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 55
Management API Definition
Index
API Details
Note
// e.g., skip=100 starts from the 101st record. “order”:”asc/desc”
// Order by time, default ascend order.
} } Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
"maxpoints": 100, // The total number of records matched. // independent of maxdatapoint and skip value "from": t1, "to": t2, "metadata": [ {"datapoint": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} {"datapoint": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} {"datapoint": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} ], “dataseries”:[ {"datapoint": "path1", “time”:t1, “value”:189} {"datapoint": "path1", “time”:t2, “value”:192} {"datapoint": "path2", “time”:t3, “value”:189} {"datapoint": "path2", “time”:t4, “value”:196} ] } Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 56
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
Notes: There are system reserved data points, prefixed with sys_*. These data points belong to gateways. The current data points include: sys_online, sys_c0, sys_c1, …, sys_c9. These data points are reserved by gateway systems to send system level data to the backend. With the rawdataquery API, the caller can specify these data points and retrieve the data. The sys_online records the on/off status of the gateway, 0 represents offline, 1 represents online. Three will be at least one datapoint per day at the beginning of the day. These system level data points cannot be managed by data point management APIs. They will not appear in the data point list API either. 4.2
String rawDataExport (String json_str); Params: Json_str structure: { “method”:”data/rawdataexport”, “auth_token”:”token”, “output”:”csv”, “time_from”:”time”,
// User token
// Could be ”csv” or “zipcsv” // Start time in epoch (float number)
“time_to”:”time”,
// End time in epoch (float number)
“project_id”:”id1”,
// Project filter
“gateway_id”: “*”,
// Gateway filter, * for wild card
“datapoint_id”:””
// data point filter, * for wild card.
} Return: (Note that this is a bi-stage API) JSON STRING {
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 57
Management API Definition
Index
API Details
Note
“retcode”: “1”,
//1 if successful, or >10000 in case of errors.
“api_qid”:”QID”;
// API query ID in ASCII format
“timeout”:”1000”;
// timeout value for stage-2 call (milliseconds)
} Notes: See 4.1. getExportStatus returns the following JSON structure: { “retcode”:”0”,
//>10000 in case of errors.
"data": “URL”
// URL where the export file can be downloaded.
} 4.3
String getExportStatus(String json_str); Function: query the status and result of data export call, similar to getAPIStatus Params: JSON structure { “method”:”data/getexportstatus”, “api_qid”:”QID”,
//API query ID from the stage-1 API call.
“auth_token”:”xxx” // user token } Return value is also in JSON format, in case of API finished execution, { “retcode”:”0”, “data”:”url”
//API return code, 0 if successful, >10000 for error // URL where exported data can be downloaded
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 58
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
} If the API call is still in progress, return { “retcode”:”1”,
// Code 1 for inprocess.
“api_qid”:”QID”,
// API query QID
“time_out”:”100”,
// Timeout value for next query, in millisecond.
} 4.4
String statsDataQuery(String json_str); Params: Json_str structure: { “method”:”data/statsdataquery”, “auth_token”:”token”,
// User token
“maxdatapoints”:”1000”, // Max number of data point to be returned, // 0 means unlimited. “time_from”:”time”,
// start time in epoch time (float format)
“time_to”:”time”,
// end time in epoch time (float format)
“project_id”:”id1”,
// Project filter, based on id.
“stats_id”:”*”,
// Stats data ID, * for wild card.
“skip”:”100”,
// Skip the first N number of record in result
// e.g., skip=100 starts from the 101st record. “order”:”asc/desc”
// Order by time, default ascend order.
} Return:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 59
Management API Definition
Index
API Details
Note
{ “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
"maxpoints": 100, "from": t1, "to": t2, "metadata": [ {"statspath": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} {"statspath ": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} {"statspath ": "path", “name”:”name”, “userdata”:uri, “datatype”:type, “dataunit”:unit} ], “dataseries”:[ {"statspath": "path1", “time”:t1, “value”:189} {"statspath": "path1", “time”:t2, “value”:192} {"statspath": "path2", “time”:t3, “value”:189} {"statspath": "path2", “time”:t4, “value”:196} ] } 4.5
String statsDataExport (String json_str); Params: Json_str structure: { “method”:”data/statsdataexport”,
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 60
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
“auth_token”:”token”, “output”:”csv”,
// User token
// could be ”csv”, “zipcsv”
“time_from”:”time”,
// Start time in epoch (float number)
“time_to”:”time”,
// End time in epoch (float number)
“project_id”:”id1”,
// Project filter
“stats_id”:”*”
// Stats data ID, * for wild card
} Return: (Note that this is a bi-stage API) JSON STRING { “retcode”: “1”,
//1 if successful, or >10000 in case of errors.
“api_qid”:”QID”;
// API query ID in ASCII format
“timeout”:”1000”;
// timeout value for stage-2 call (milliseconds)
}
getExportStatus returns the following JSON structure: { “retcode”:”0”,
//>10000 in case of errors.
"data": “URL”
// URL where the export file can be downloaded.
}
4.6
String alarmDataQuery(String json_str); Params: Json_str structure:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 61
Management API Definition
Index
API Details
Note
{ “method”:”data/alarmdataquery”, “auth_token”:”token”,
// User token
“maxdatapoints”:”1000”, // Max number of data point to be returned, // 0 means unlimited. “time_from”:”time”,
// start time in epoch time (float format)
“time_to”:”time”,
// end time in epoch time (float format)
“project_id”:”id1”,
// Project filter, based on id.
“tag”:”*”,
// Filter based on alarm tag, * for wild card
“skip”:”100”,
// Skip the first N number of record in result
// e.g., skip=100 starts from the 101st record. “order”:”asc/desc”
// Order by time, default ascend order.
} Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
"maxpoints": 100, "from": t1, "to": t2, “dataseries”:[ {"tag": "tag1", “time”:t1, “value”:msg1, “code”: code, “gateway_id”: id, “alarm_id”: sequence_number}, {"tag": "tag2", “time”:t2, “value”:msg2, “code”: code, “gateway_id”: id, “alarm_id”: sequence_number } ] Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 62
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
} Note: There are specified ranges for the alarm code. Code 2500029999 are for gateway alarm, code 35000-39999 for gateway log code, and code 80000-89999 are free for application to usage. 4.7
String alarmDataExport (String json_str); Params: Json_str structure: { “method”:”data/alarmdataexport”, “auth_token”:”token”, “output”:”csv”,
// User token
// could be ”csv”, “zipcsv”
“time_from”:”time”,
// Start time in epoch (float number)
“time_to”:”time”,
// End time in epoch (float number)
“project_id”:”id1”,
// Project filter
“tag”:”*”
// alarm filter, * for wild card.
} Return: (Note that this is a bi-stage API) JSON STRING { “retcode”: “1”, “api_qid”:”QID”; “timeout”:”1000”;
//1 if successful, or >10000 in case of errors. // API query ID in ASCII format // timeout value for stage-2 call (milliseconds)
}
getExportStatus returns the following JSON structure:
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 63
Management API Definition
Index
API Details
Note
{ “retcode”:”0”,
//>10000 in case of errors.
"data": “URL”
// URL where the export file can be downloaded.
}
4.8
String pollAlarm (String json_str); Params: Json_str structure: { “method”:”alm/pollalarm”, “auth_token”:”token”, “project_id”:”id”
// User token
// project ID
“timeout”:”time”,
// timeout value in milliseconds.
“last_seq”:”seq”
// sequence number from last query, may be ””
} Return: JSON STRING if alarm is found. { “retcode”: “0”, “retry”:”timeout”,
//0 if successful // retry after specified milliseconds.
“gateway_id”:”gw_id”, // gateway ID of the alarm is from. “timestamp”:”time”, // epoch time of the alarm generated time “seq”:”seq number”, // sequence number of this alarm. “code”:”code”,
// alarm code or type of alarm.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 64
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
“tag”:”tag”,
Note
// user defined tag on this alarm.
“message”:”msg”
// alarm content.
} If no alarm is found, { “retcode”: “2”,
//2 if successful.
“retry”:”timeout”,
// retry after specified milliseconds.
} If error happens, { “retcode”:”code”,
// >10000 error code.
“reason”:”failed reason” }
4.5
Log Management API The log management APIs provide interfaces to query and export system log. This is only available to platform admins.
Table 13. Log Management APIs Index
API Method and Path
Functionality
5.1
POST logs/rawlogquery
Query log data with filter.
5.2
POST logs/rawlogexport
Export raw log data.
5.3
POST logs/getservicestats
Obtain running stats of server.
August 2015 Document Number: 332845-001US
Priority
2
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 65
Management API Definition
The following are the API details in JAVA language syntax. Table 14. Log Management API Details Index
API Details
Note
5.1
String rawLogQuery(String json_str); Params: Json_str structure: { “method”:”logs/rawlogquery”, “auth_token”:”token”,
// User token
“maxdatapoints”:”1000”, // Max number of data point to be returned, // 0 means unlimited. “time_from”:”time”,
// start time in epoch time (float format)
“time_to”:”time”,
// end time in epoch time (float format)
“log_tag”:”Web”,
// Log type filter, * for wild card.
“skip”:”100”,
// Skip the first N number of record in result
// e.g., skip=100 starts from the 101st record. “order”:”asc/desc”
// Order by time, default ascend order.
} Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
"maxpoints": 100, "from": t1, "to": t2, “entries”:[
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 66
August 2015 Document Number: 332845-001US
Management API Definition
Index
API Details
Note
{"time": t1, “tag”:”Web”, “value”:”user logined.”} {"time": t2, “tag”:”Web”, “value”:”user logined.”} {"time": t3, “tag”:”Web”, “value”:”user logined.”} ] } 5.2
String rawLogExport (String json_str); Params: Json_str structure: { “method”:”logs/rawlogexport”, “auth_token”:”token”, “output”:”csv”,
// User token
// could be ”csv”, “zipcsv”
“time_from”:”time”,
// Start time in epoch (float number)
“time_to”:”time”,
// End time in epoch (float number)
“log_tag”:”Web”,
// Log type filter, * for wild card.
} Return: (Note that this is a bi-stage API) JSON STRING { “retcode”: “1”, “api_qid”:”QID”; “timeout”:”1000”;
//1 if successful, or >10000 in case of errors. // API query ID in ASCII format // timeout value for stage-2 call (milliseconds)
}
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 67
Management API Definition
Index
API Details
Note
API 4.3: getExportStatus returns the following JSON structure: { “retcode”:”0”,
//>10000 in case of errors.
"data": “URL”
// URL where the export file can be downloaded.
}
5.3
String getServiceStats(String json_str); Params: Json_str structure: { “method”:”logs/getservicestats”, “auth_token”:”token”,
// User token
} Return: { “retcode”:”0”
// 0 if successful, or >10000 in case of errors.
"uptime": “value”,
// system uptime in milliseconds.
"log_written": “value”, // number of log entries since last restart "failed_login": “value”, // number of login fails since last restart “gw_cmds”: “value” // number of gateway command since restart. }
§
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 68
August 2015 Document Number: 332845-001US
Error Code Range
5.0
Error Code Range The error codes of the system are pre-allocated in the following ranges.
Table 15. Error Code Ranges Error code
Purpose
Note
0
Reserved for API call return (successful)
1
Reserved for API call return
10000-18999
Reserved for API system error code
19000-19999
Reserved for API SDK return code
20000-24999
Reserved
25000-29999
Allocated for gateway alarms
30000-34999
Reserved
35000-39999
Gateway log code
Usable for integration
80000-89999
Allocated for applications to use
Usable for integration
Usable for integration
§
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 69
API List
Appendix A API List Table 16. API List Index
API Method and Path
Description
Group
A.1
POST dev/ctl/getVer
Get gateway version.
A.2
POST dev/ctl/getcfg
Get gateway configuration.
Device control
A.3
POST dev/ctl/setcfg
Set gateway configuration.
A.4
POST dev/ctl/ping
Get the gateway online status.
A.5
POST dev/ctl/updatefirmware
Update gateway firmware.
A.6
POST dev/ctl/system
Execute customized system command.
A.7
POST dev/ctl/getapplist
Get list of applications on gateway.
A.8
POST dev/ctl/startapp
Start one application.
A.9
POST dev/ctl/stopapp
Stop one application.
A.10
POST dev/ctl/installapp
Install one application.
A.11
POST dev/ctl/reboot
Restart the gateway.
A.12
POST dev/ctl/filec2d
Transfer a file from cloud to device.
A.13
POST dev/ctl/filed2c
Transfer a file from device to cloud.
A.14
POST dev/ctl/rpccall
Call device RPC.
A.15
POST dev/ctl/getapistatus
Get API execution status.
A.16
POST dev/ctl/listcfg
List gateway configuration.
A.17
POST dev/ctl/preparelog
Gateway put log into a local file.
A.18
POST dev/ctl/filestats
Return information of local file.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 70
August 2015 Document Number: 332845-001US
API List
1.1
POST admin/user/adduser
Add user with certain roles.
1.2
POST admin/user/updateuser
Modify user information.
1.3
POST admin/user/getusrinfo
Get user information.
1.4
POST admin/user/setpass
Set user password.
1.5a
POST admin/user/userlogin1
The login interface for all users.
1.5b
POST admin/user/userlogin2
User login with password.
1.6
POST admin/user/userlogout
The login interface for all users.
1.7
POST admin/tokens/listtokens
List all active tokens.
1.8
POST admin/tokens/deltoken
Delete one token.
1.9
POST admin/user/setapikey
Set the public key for API user.
1.10
POST admin/user/apilogin2
API user login with keys.
2.1
POST admin/project/addproject
Create a new project (platform admin only).
2.2
POST admin/project/updateproject
Update project information.
2.3
POST admin/project/getprojectinfo
Get project information.
2.4
POST admin/project/deleteproject
Delete a project (platform admin only).
2.5
POST admin/project/listprojects
List all projects in the platform.
2.6
POST admin/project/listdevinproject
List matched device in a project.
2.7
POST admin/project/getprojectstats
Return project stats data.
2.8
POST admin/project/listprojectusers
List all users in a project.
3.1
POST admin/dev/adddev
Add a new device entry.
3.2
POST admin/dev/updatedev
Update device information.
August 2015 Document Number: 332845-001US
User mngt
Project mngt
Device mngt
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 71
API List
3.3
POST admin/dev/getdevinfo
Get device information.
3.4
POST admin/dev/deletedev
Delete a device entry.
3.5
POST admin/dev/adddatapoint
Add a data point to a device.
3.6
POST admin/dev/updatedatapoint
Remove data point from device.
3.7
POST admin/dev/deletedatapoint
Update data point information.
3.8
POST admin/dev/getdatapointinfo
Get data point information.
3.9
POST admin/dev/listdatapoints
List data point in a project.
3.10
POST admin/group/addgroup
Add a group in this project.
3.11
POST admin/group/updategroup
Update group information.
3.12
POST admin/group/getgroupinfo
Get group information.
3.13
POST admin/group/deletegroup
Delete a group.
3.14
POST admin/group/listgroups
List groups in the project.
3.15
POST admin/project/listdevbygroup
List devices by group.
3.16
POST admin/dev/listdatapointbygroup
List data point by group.
3.17
POST admin/group/listgrouppath
List hierarchy path of a group.
3.18
POST admin/dev/getdevkey
Get the device key of a device.
4.1
POST data/rawdataquery
Query raw data by filters.
4.2
POST data/rawdataexport
Export raw data.
4.3
POST data/getexportstatus
Get the data export status.
4.4
POST data/statsdataquery
Query stats data by rules.
4.5
POST data/statsdataexport
Export stats data.
4.6
POST data/alarmdataquery
Query alarm data.
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 72
Data mngt
August 2015 Document Number: 332845-001US
API List
4.7
POST data/alarmdataexport
Export alarm data.
4.8
POST alm/pollalarm
Poll alarm.
5.1
POST logs/rawlogquery
Query log data with filter.
5.2
POST logs/rawlogexport
Export raw log data.
5.3
POST logs/getservicestats
Obtain running stats of server.
Log mngt
§
August 2015 Document Number: 332845-001US
Gateway Management Solution Based on Intel® IoT Platform API Reference Manual 73
