Part 3. Cloud API: APP Service APIs

Device Group Endpoints

Click an ▶ API endpoint to expand/collapse its content.
POST/device-groups/share/account/:account_id
Purpose: The user adds view permission of the device group to the other users, so that the users are allowed to view all the devices in the device group.
Request Method
POST
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The account_id of the user who shares the device group.
Required devgroups Array The array of the devgroup_id. 
[
    c92be72d-40fc-462f-ae52-9e997e514277,
    gasdkoeo-5bps-vspe-4ojd-smov4w2v5019
  ]
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.
400 INVALID_DEVICEGROUP_ID The devgroup_id does not exist.
400 SHARE_TO_MYSELF The target user you share cannot be yourself (Error message will be sent when a single error is happening.).
400 SHARE_TO_SAME_ACCOUNT_ID You have already shared the device group with the account (Error message will be sent when a single error is happening.).

▲ Top

DELETE/device-groups/share/account/:account_id
Purpose: The user deletes the user's view permission of the device group, so the users are not allowed to view all the devices in the device group.
Request Method
DELETE
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user's account_id.
Required devgroups Array The array of the devgroup_id. 
[
    c92be72d-40fc-462f-ae52-9e997e514277,
    gasdkoeo-5bps-vspe-4ojd-smov4w2v5019
  ]
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.
400 INVALID_DEVICEGROUP_ID The devgroup_id does not exist.

▲ Top

GET/device-groups/account/:account_id
Purpose: The user gets the list of the device group based on the user's account_id.
Request Method
GET
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user's account_id.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicegroups Object (Array) Get the list of the device group.
Return Values in the devicegroups array
Fields Type Description
devgroup_id String The ID number of the device group.
devgroup_name String The name of the device group.
devgroup_status Integer The status of the device group.
  • 0 = Deactivated
  • 1 = Activated
devgroup_sequence Integer The sequence of the device group.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicegroups": [{
    "devgroup_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devgroup_name": "baby-group",
    "devgroup_status": 1,
    "devgroup_sequence": 1
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID account_id does not exist.

▲ Top

GET/device-groups/share/account/:account_id
Purpose: Gets the list of the shared device group based on the user's account_id.
Request Method
GET
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user’s account_id.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devicegroups Object (Array) Get the list of the device group.
Return Values in the "devicegroups" array
Fields Type Description
devgroup_id String The ID number of the device group.
devgroup_name String The name of the device group.
devgroup_status Integer The status of the device group.
  • 0 = Deactivated
  • 1 = Activated
devgroup_sequence Integer The sequence of the device group.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devicegroups": [{
    "devgroup_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "devgroup_name": "baby-group",
    "devgroup_status": 1,
    "devgroup_sequence": 1
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.

▲ Top

POST/device-groups/account/:account_id
Purpose: The user adds the device group information based on the user's account_id.
Request Method
POST
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required devgroup_name String The name of the device group.
  • Device group name must not include certain characters.
  • Invalid characters are ^ @ , & = * ' "
    • Caret (^)
    • At sign (@)
    • Comma (,)
    • Ampersand (&)
    • Equals (=)
    • Asterisk (*)
    • Double quote (")
    • Single quote (')
Required devgroup_sequence Integer The sequence of the device group.
Required devgroup_status Integer The status of the device group.
  • 0 = Deactivated
  • 1 = Activated
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
devgroup_id String The ID number of the device group.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "devgroup_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.

▲ Top

PUT/device-groups/:devgroup_id/account/:account_id
Purpose: The user updates information of the device group based on the user's account_id and devgroup_id.
Request Method
PUT
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user's account_id.
Required devgroup_id String The ID number of the device group (devgroup_id).
Required devgroup_name String The name of the device group.
Required devgroup_sequence Integer The sequence of the device group.
Required devgroup_status Integer The status of the device group.
  • 0 = Deactivated
  • 1 = Activated
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.
400 INVALID_DEVICEGROUP_ID The devgroup_id does not exist.
400 SAME_DEVICEGROUP_NAME The devgroup_name already exists.

▲ Top

DELETE/device-groups/:devgroup_id/account/:account_id
Purpose: The user deletes the device group based on the ID number of the user's account_id and devgroup_id.
Request Method
DELETE
Changelog
Aug 21, 2017 First version
Oct 11, 2017 Second version
Dec 21, 2017 Third version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The user's account_id.
Required devgroup_id String The ID number of the device group.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.
400 INVALID_DEVICEGROUP_ID The devgroup_id does not exist.
400 DEVICES_STILL_EXIST_IN_THE_DEVICEGROUP The device still exists in the device group.

▲ Top