Part 3. Cloud API: APP Service APIs

Device Endpoints

Click an ▶ API endpoint to expand/collapse its content.
POST/devices/:device_id/device-group/:devgroup_id
Purpose: The user adds the specific device to 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 device_id String The ID number of the device.
Required devgroup_id String The ID number of the device group.
Required account_id String The account_id of the user.
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 INVALID_DEVICE_ID The device_id does not exist.

▲ Top

POST/devices/share/account/:account_id
Purpose: The user adds view permission of the device to the other users.
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 user’s account_id.
Required devices Array The array of the device_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_DEVICE_ID The device_id does not exist.
400 SHARE_TO_MYSELF You cannot share the device with yourself (Error message will be sent when a single error is happening.).
400 SHARE_TO_SAME_ACCOUNT_ID You have already share the device with the account (Error message will be sent when a single error is happening.).

▲ Top

DELETE/devices/share/account/:account_id
Purpose: The user removes the other user's view permission of the device.
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 devices Array The array of the device_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_DEVICE_ID The device_id does not exist.

▲ Top

POST/devices
Purpose: The users add their own device information.
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 device_name String The name of the device.
  • Device name must not contain certain characters.
  • Invalid characters are ^ @ , & = * ' "
    • Caret (^)
    • At sign (@)
    • Comma (,)
    • Ampersand (&)
    • Equals (=)
    • Asterisk (*)
    • Double quote (")
    • Single quote (')
Required device_ip String The IP address of the device.
Required account_id String The account id that the device belongs to.
Required device_attribute Object The attribute key and value of the device.
  • For example,
    {
  "name": "resolution",
  "value": "1080p"
}
Required Devicemode_id String The DeviceMode that the device belongs to.
Required device_port Integer The port number of the device.
Required device_location String The location of the device.
Required device_mac String MAC address of the device.
Required device_account String Default account to log into the device (editable).
Required device_password String Default password to log into the device (editable).
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
device_id String The ID number of the device.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "device_id": "c92be72d-40fc-462f-ae52-9e997e514277"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 SAME_DEVICE_MAC MAC Address already exits. MAC address must be unique.
400 SAME_DEVICE_SETTING Same device IP or port.
400 SAME_DEVICE_NAME Same device_name.
400 INVALID_SCENEMODE_ID The Devicemode_id does not exist.

▲ Top

GET/devices/share/account/:account_id
Purpose: The user adds the view permission of the device to the other users.
Request Method
GET
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 devices Array The array of the device_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_DEVICE_ID The device_id does not exist.
400 SHARE_TO_MYSELF You cannot share the device with yourself (Error message will be sent when a single error is happening.).
400 SHARE_TO_SAME_ACCOUNT_ID You have already share the device with the account (Error message will be sent when a single error is happening.).

▲ Top

GET/devices/:device_id
Purpose: Gets the information of the device based on the device_id.
Request Method
GET
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 belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required device_id String The ID number of the device.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
device_id String The ID number of the device.
device_name String The name of the device.
device_ip String The IP address of the device.
device_attribute Array (Object) The attribute key and value of the device. For example,
[
  {
    "name": "resolution",
    "value": "1080p"
  }
]
Devicemode_id Integer The DeviceMode that the device belongs to.
device_port Integer The port number of the device.
device_location String The installing location of the device.
device_mac String The MAC address of the device.
device_account String Default account to login to the device (editable).
device_password String Default password to log into the device (editable).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "device_id": "c92be72d-40fc-462f-ae52-9e997e514277",
  "device_name": "living room",
  "device_ip": "211.111.333.555",
  "device_attribute": [{
    "name": "resolution",
    "value": "1080p"
  }],
  "Devicemode_id": "c9se4e72d-40fc-462f-ae52-9e99g4g6o14277",
  "device_port": 1234,
  "device_location": "taipei",
  "device_mac": "12gd-56ae-34pld-89bwde",
  "device_account": "nice-camera",
  "device_password": "nicecamera"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_DEVICE_ID device_id does not exist.

▲ Top

PUT/devices/:device_id
Purpose: The user updates the device information based on the device_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 belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required device_id String The ID number of the device.
Required device_name String The name of the device.
Required device_ip String The IP address of the device.
Required device_attribute Object The attribute key and value of the device. For example, 
{
  "name": "resolution",
  "value": "1080p"
}
Required Devicemode_id Integer The DeviceMode the device belongs to.
Required device_port Integer The port number of the device.
Required device_location String The location of the device.
Required device_mac String The MAC address of the device.
Required device_account String Default account to log into the device (editable).
Required device_password String Default password to log into the device (editable).
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 SAME_DEVICE_MAC MAC Address already exits. MAC address must be unique.
400 SAME_DEVICE_SETTING Same device IP or port.
400 SAME_DEVICE_NAME Same device_name.
400 INVALID_SCENEMODE_ID The Devicemode_id does not exist.

▲ Top

DELETE/devices/:device_id
Purpose: The user deletes the device based on the device_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 device_id String The ID number of the device.
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_DEVICE_ID device_id does not exist.

▲ Top

GET/devices/:device_id/attributes
Purpose: The user gets the camera capability, for example: resolutions, frame rate, sensor type, ..., according to the device_id.
Request Method
GET
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 device_id String The ID number of the device.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
attributes Array Get the list of the attribute.
Return values in the "attributes" array
Fields Type Description
attribute_id String The ID number of the attribute.
attribute_name String The name of the attribute.
attribute_value String The value of the attribute.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "attributes": [{
    "attribute_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "attribute_name": "resolution",
    "attribute_value": "1080p"
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 SAME_DEVICE_ID device_id does not exist.

▲ Top

POST/devices/zone
Purpose: The API is invoked when the user marks the "Region of Interest" (ROI) while viewing the recorded videos or photos on the device.
Notes
The marked ROI returns the x and y coordinates and each position of the array will be stored.
Request Method
POST
Changelog
Dec 21, 2017
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 device_id String The ID number of the device.
Required zones Array The marked area for the location on image. For example: 
[{"zone_x":100, "zone_y":100}],
  [{"zone_x":200, "zone_y":200}]
The coordinates of marked location. For example: 
[{"zone_x":100, "zone_y":100}],
  [{"zone_x":200, "zone_y":200}]
Request parameters in the "zones" array
Need Parameter Type Description
Required zone_x Integer X-coordinate of the marked location.
Required zone_y Integer Y-coordinate of the marked location.
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": 123
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_DEVICE_ID device_id does not exist.

▲ Top