CoolKit IoT Cloud API
Version：1.1
Confidential
ChangeLog:
version change author date
1.0 Creation Johnson 2016.4.6
1.1 2.3.4 add timer example Johnson 2016.7.26
1.1 version changed from 2 to 4
2.2.1 add uiid parameter
1 Common Constraint
1.1 General
HTTP request header : Content-Type:application/json
Character encoding：utf-8
HTTP request mandatory parameter in Server REST（put in querystring when use
Get method，put in body json when use POST method）：
name type comment
ts long unix timestamp, in seconds from 1970.1.1
appid string allocated from CoolKit
nonce string hex string from 4-byte random integer
version int 4 protocol version
Must have signature or access token in HTTP Authorization Header
All HTTP and websocket should use SSL/TLS( except device interface)，port is
8080, support SSLv3, TLS 1.1,1.2
1.2 Signature
All interface before login (including login interface) need signature, signature is put in
Authorization header, like:
Authorization:Sign bhCQXTVyfj5cmA9uKkPFx1zeOXM=
GET request：
Sort all parameter (except sign) alphabetically, connect with &. like :
appid=7284397484&deviceid=59&nonce=2323dfgh¶=xxxx &ts=1374908054
Using app secret as key，generate signature by HMAC-SHA256 。
Encode signature with BASE64 and put it in Authorization header。
POST request :
The whole body json is as the data to sign, like：
{“appid”:7284397484,”deviceid”:”59”,”nonce”:”232323df”,ts=1374908054}
java example code：
nodejs example code：
1.3 Access token
All interface after login need access token in Authorization header, like:
Authorization: Bearer 1832d4a0f5f5f5845cb1922c1091c8aa5dfe0041
Login interface will return access token if login succeed.
1.4 Error code
0, succeed
400, request parameter error
401, authentication fail
402 , access token expire, should let user login.
403, no permission to call this interface
406, an unauthorized connection
500, internal error
1.5 Add device call flow
1.6 Build websocket connection flow
2 API
2.1 Device
When device in AP pairing mode, its IP address is 10.10.7.1 .
2.1.1 query device info
Comment: return factory apikey to app
URL: http://device_ip_address/device
method: GET
request parameter: None
response：
ID name type allow NULL comment
1 apikey String N factory apikey
2 deviceid String N
3 accept String N post or get
2.1.2 pair
Comment: app post server domain name ,port and wifi ssid, password to device
URL: http://device_ip_address/ap
method: POST or GET ( according to 2.1.1 return result , default POST)
request parameter：
ID name type allow NULL comment
1 ssid String N wifi ssid
2 password String Y Wifi password
3 serverName String N after login, app get region
(for example cn) and build
domain name like：
cn-disp.coolkit.cc
4 port Int N server port, default 443
response：
ID name type allow NULL comment
1 error Int N 0 is OK
other is error
2 reason String Y
2.2 Server REST
2.2.1 query user device list
Comment: user device list
URL: https://region-api.coolkit.cc:8080/api/user/device (region is cn/eu/us, got from 2.2.6
login interface response )
method: get
request parameter:
ID name type allow NULL comment
1 apikey String N user apikey
2 lang String Y cn to get Chinese response
en to get English response
response:
ID name type allow NULL comment
1 error String Y if no error, will be null
2 devices [Device] N device info list
Device definition:
ID name type allow NULL comment
1 name String N device name
2 type String N type
3 deviceid String N device ID
4 apikey String N user apikey
5 extra Object N device factory info
6 brandName String N brand name
7 productModel String N product model
8 groups [String] Y group ids device belong to,
could belong to multiple
groups
9 uiid Int N 1 single channel switch
2 dual channel switch
3 three channel switch
4 four channel switch
example:
"extra":{"_id":"55f280631ed44d9a3a637f51","extra":{"model":"PSB-B04-TS","ui":"four channel
","description":"desc（PSB-B04-
TS）","manufacturer":"CK","mac":"0c:c1:00:00:00:78","apmac":"0c:c1:00:00:00:79","modelInfo"
:"55f280161ed44d9a3a637f47","brandId":"55f27e661ed44d9a3a637f3f"}},"__v":0,"
2.2.2 add device
Comment: add device to account
URL: https://region-api.coolkit.cc:8080/user/device/add
method: post
request parameter:
ID name type allow NULL comment
1 apikey String N user apikey
2 name String N
3 deviceid String N
4 subDeviceId ObjectId Y if isSub is 1, subDeviceId no
null
5 isSub String N if add sub device
0：no (default)
1：yes
response：
ID name type allow NULL comment
1 devices [Object] Y sub device list
2.2.3 delete device
Comment：delete device from user
URL: https://region-api.coolkit.cc:8080/user/device/:deviceid
method： delete
request parameter：
ID name type allow NULL comment
1 apikey String N user apikey
2 deviceid String N if isSub is 0, deviceid not null
3 subDeviceId ObjectId N if isSub is 1, subDeviceId not
null
4 isSub String N is sub device
0：no (default)
1：yes
response：
ID name type allow NULL comment
1 devices [Object] N sub device list
2.2.4 query region
Comment: query user region before register
URL: https://api.coolkit.cc:8080/api/user/region
method: get
request parameter:
response：
ID name type allow NULL comment
1 error int N 0: succeed
500: internal error
1 region String N region：
cn : Asia
us : America
eu : Europe
2 requestid String Y ts+”-”+nonce
2.2.5 register
Comment：register
URL: https://region-api.coolkit.cc:8080/api/user/register (region is got from 2.2.2)
method: post
request parameter:
ID name type allow NULL comment
1 email String Y if user input email
2 phoneNumber String Y if user input phone Number
3 verificationCode String N verification code
4 password String N
response：
ID name type allow NULL comment
1 error Int N 0: succeed
401: auth fail
500: server error
498: verification code error
409: user already exist
2 user User N user info
3 at String N Access Token
4 rt String N Refresh Token
5 region N
User Definition:
ID name type allow NULL comment
1 apikey String N user id
2 phoneNumber String N
3 email String N
4 createdAt Date N
2.2.6 login
Comment: login
URL: https://api.coolkit.cc:8080/api/user/login
method: post
request parameter:
ID name type allow NULL comment
1 email String Y
2 phoneNumber String Y
3 password String N
response：
ID name type allow NULL comment
1 error Int N 0:succeed
400: parameter error
301：user not in default
region, app need to access
region-api.coolkit.cc to login
401: password error
402：mail not activated
404：user not exist
500：server error
4 user User N
5 at String N Access Token
6 rt String N Refresh Token
7 region N
2.2.7 send verification code
Comment: send verification code to phone number or email address
URL: https://region -api.coolkit.cc:8080/api/sms
method: post
request parameter:
ID name type allow NULL comment
1 sendType Int N 0 when register
1 when reset password
2 email String Y
3 to String Y if mobile phone
format: +8615815725225
response：
ID name type allow NULL comment
1 error Int N 0:succeed
301：user not in default
region, app need to access
region-api.coolkit.cc to send
verification code
404：account not exist
500：server error
504：send fail
2 region N when error is 301 , will return
region
2.2.8 reset password
Comment: reset password
URL: https://region -api.coolkit.cc:8080/api/user/reset
method: post
request parameter:
ID name type allow NULL comment
1 email String Y
2 phoneNumber String Y
3 verificationCode String N
4 password String N
response：
ID name type allow NULL comment
1 error Int N 0:succeed
400: parameter
498：auth fail
500：server error
2.2.9 create group
Comment: create group for device
URL: https://region -api.coolkit.cc:8080/api/group
method: post
request parameter:
ID name type allow NULL comment
1 apikey
1 name String N group name
2 Index int Y group position
If index is null, will see as last
group, server will give max
index value to this group
begin from 1.
If index is not null, server will
increase group index value
that equal and bigger than it.
response：
ID name type allow NULL comment
1 error Int N see 1.4
2 groupid String N group ID
2.2.10 modify group
Comment: modify group name, index
URL: https://region -api.coolkit.cc:8080/api/group
method: put
request parameter:
ID name type allow NULL comment
1 id String N group id
1 name String Y
2 Index index Y
response：
ID name type allow NULL comment
1 error Int N see 1.4
2.2.11 delete group
Comment: 跟组分组 id 删除一个设备分组
URL: https://region -api.coolkit.cc:8080/api/group
method: delete
request parameter:
ID name type allow NULL comment
1 id String N group id
2 type int N 0: only delete group
1: delete group and all
devices belong to it
response：
ID name type allow NULL comment
1 error Int N see 1.4
2.2.12 add device to group
Comment: move devices to group
URL: https://region -api.coolkit.cc:8080/api/group/addDevice
method: post
request parameter:
ID name type allow NULL comment
1 deviceinfos [Device] N
Device definition:
ID name type allow NULL comment
1 source_id String Y source group ID
2 target_id String N target group ID
3 deviceid String N
4 type int Y 0: only overwrite source
group id
1: delete all groups device
belong to and set device to
target_id
response：
ID name type allow NULL comment
1 error Int N
2.2.13 query user group
Comment: query user group
URL: https://region -api.coolkit.cc:8080/api/group
method: get
request parameter:
ID name type allow NULL comment
1 apikey String N user apikey
response：
ID name type allow NULL comment
1 error String N
2 groupinfos [GroupInfos] Y
GroupInfos
ID name type allow NULL comment
1 id String N group id
2 name String N
3 index int N
4 createdAt Date N create time
2.3 Server Websocket
Comment：All based on websocket except dispatch interface.
Client need to keep sending websocket ping according to handshake response
to keep connection alive. If client can’t receive server pong response, client need to close
connection and create new one.
websocket url: wss://ip_address:port/api/ws , should customerize SSL
certificate verify process to use ip address
2.3.1 dispatch（HTTP REST）
Comment：App shoud use call this interface to get websocket information like server ip
address , port before create websocket connection.
Attention： access token should be in HTTP Authorization header
URL: https://region-disp.coolkit.cc:8080/dispatch/app
method: post
request parameter:
ID name type allow NULL comment
1 accept String N only support ws now
could be：
mqtt,ws
2 version int N 2
3 imei String Y if mobile phone app, provide
imei/meid
4 appid String N
5 ts int N timestamp
6 nonce String N
7 model String Y if mobile phone app, provide
phone model
8 os String Y android
ios
or other
9 romVersion String y android or ios version
response：
ID name type allow NULL comment
1 error Int N see 1.4
2 reason String Y error reason
3 requestid String Y ts+”-”+nonce
4 IP String N websocket server IP
5 port Int N websocket server port
6 domain String Y websocket server domain
2.3.2 handshake
Comment：
request parameter:
ID name type allow NULL comment
1 action String N userOnline
2 version int N 2
3 imei String N
4 ts int N
5 model String Y
6 os String Y android
ios
or other
7 romVersion String Y
8 at String N access token
10 userAgent String N app
11 apikey String N user apikey
12 appid String N
13 nonce String N
14 sequence long N current milliseconds
response：
ID name type allow NULL comment
1 error Int N
2 apikey String Y
3 config PARAMS Y
PARAMS 定义：
ID name type allow NULL comment
1 hb Int Y heartbeat switch
0 off
1 on
if off, client don’t need to
send ping. default is on.
2 hbInterval Int Y heartbeat interval in
seconds.
client need to use this value
plus 7 as interval to send
ping.
If null, use 12 seconds as
default.
2.3.3 device online/offline
Comment：notify device online/offline to app
request parameter:
ID name type allow NULL comment
1 action String N sysmsg
2 apikey int N user apikey
3 deviceid String N
4 params PARAMS N
PARAMS 定义
ID name type allow NULL comment
1 online String N true: online
false:offline
2.3.4 update device status
Comment： update status of device
request parameter:
ID name type allow NULL comment
1 action String N update
2 apikey int N user apikey
3 deviceid String N
4 userAgent String N should be app
5 selfApiKey String Y current user’s apikey . if the
device is shared by other.
6 sequence String Y
7 params PARAMS N device protocol. according to
device’s ui type.
PARAMS ：
switch on/off example：
single channel switch：
"params":{
"switch":"on"
multiple channel switch：
"params": {
"switches": [
"switch": "off",
"outlet": 0
},
"switch": "off",
"outlet": 1
},
"switch": "off",
"outlet": 2
},
"switch": "off",
"outlet": 3
response：
ID name type allow NULL comment
1 error Int N 503 Device Offline
504 Request Timeout
2 apikey int N user apikey
3 deviceid String N
4 sequence
2.3.5 query device status
Comment：query device stutus
request parameter:
ID name type allow NULL comment
1 action String N query
2 apikey int N user apikey
3 deviceid String N
4 userAgent String N app: app
6 params [String] N query keys
params example：
[ "switch" , " timers"]
response：
ID name type allow NULL comment
1 error Int N
2 apikey int N user apikey
3 deviceid String N
4 params PARAM query result
example 1, return switch status：
{ "error": 0, "apikey": "123e4567e89b12d3a456426655440000",
"deviceid": "01ad0253f2", "params": { "switch": "on" } }
example 2, no query result:
{ "error": 0, "apikey": "123e4567e89b12d3a456426655440000",
"deviceid": "01ad0253f2", "params": { } }
2.3.6 share
Comment：share to other people
request parameter:
ID name type allow NULL comment
1 apikey String N
2 deviceid String N
3 action String N share
4 userAgent String N app
5 params ShareParam N
6 sequence String N
ShareParam definition：
ID name type allow NULL comment
1 uid String Y email or phone number
2 deviceName String Y
3 userName String Y
response：
ID name type allow NULL comment
1 error Int N
2 result int Y
0 target offline, fail
1 account not exist
2 user accept share
3 user decline share
4 already shared
5 timeout (3 miniutes)
2 apikey String
3 deviceid String
4 sequence String
2.3.7 cancel share
Comment： cancel share
request parameter:
ID name type allow NULL comment
1 apikey String N
2 deviceid String N
3 action String N cancelShare
4 userAgent String N app
5 params ShareParam N
6 sequence String N
ShareParam 定义：
ID name type allow NULL comment
1 uid String Y email or phone number
response：
ID name type allow NULL comment
1 error Int N
2 sequence String N
