APIs Related to Device Control

API List

Request method	API	description
GET	/v1.0/osaas/functions/{category}	API for Obtaining the Function Set as per Category.
GET	/v1.0/osaas/devices/{device_id}/functions	API for Obtaining the Function Set as per Device.
GET	/v1.0/osaas/devices/{device_id}/specifications	API for Obtaining Device Specifications.
GET	/v1.0/osaas/devices/{device_id}/status	API for Obtaining the Latest Device Status.
POST	/v1.0/osaas/devices/{device_id}/commands	API for Issuing Device Commands.

API for Obtaining the Function Set as per Category

API Description

You can use this API to obtain the function set as per device category.

API Address

GET {url}/v1.0/osaas/functions/{category}

Request Parameters

Parameter	Type	Position	Description	Mandatory
category	String	URI	Category alias, for example, kg, cz, or dj.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
category	String	Product category.
functions	Array	Function set.

Parameters in functions

Parameter	Type	Description
code	String	Function code.
type	String	Function type.
values	String	Parameter value range.
name	String	Function name.
desc	String	Function description.

Request Example

GET {url}/v1.0/osaas/functions/kg

Success Response Example

{
  "success": true,
  "t": 1571293776551,
  "result": {
    "category": "kg",
    "functions": [
      {
        "name": "Switch",
        "desc": "Switch",
        "code": "switch_1",
        "type": "Boolean",
        "values": "{}"
      }
    ]
  }
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining the Function Set as per Device

API Description

You can use this API to obtain the function set as per the unique ID of the device.

API Address

GET /v1.0/osaas/devices/{device_id}/functions

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
category	String	Product category.
functions	Array	Function set.

Parameters in functions

Parameter	Type	Description
code	String	Function code.
type	String	Function type.
values	String	Parameter value range.
name	String	Function name.
desc	String	Function description.

Request Example

GET {url}/v1.0/osaas/devices/6c5cc1ce9718******/functions

Success Response Example

{
  "success": true,
  "t": 1571293776551,
  "result": {
    "category": "cz",
    "functions": [
      {
        "name": "Switch",
        "desc": "Switch",
        "code": "switch_1",
        "type": "Boolean",
        "values": "{}"
      }
    ]
  }
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Device Specifications

API Description

You can use this API to obtain device specifications based on the unique ID of the device.

API Address

GET /v1.0/osaas/devices/{device_id}/specifications

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object

Parameters in result

Parameter	Type	Description
category	String	Product category.
functions	Arrays	Function set.
status	Arrays	Status set.

Parameters in functions

Parameter	Type	Description
code	String	Function code.
type	String	Function type.
values	String	Parameter value range.

Parameters in status

Parameter	Type	Description
code	String	Status code
type	String	Status type
values	String	Parameter value range

Request Example

GET {url}/v1.0/osaas/devices/6c5cc1ce9718d******/specifications

Success Response Example

{
  "success": true,
  "t": 1571201730542,
  "result": {
    "category": "dj",
    "functions": [
      {
        "code": "switch_led",
        "type": "Boolean",
        "values": "{}"
      },
      {
        "code": "work_mode",
        "type": "Enum",
        "values": "{\"range\":[\"colour\"]}"
      }
    ],
    "status": [
		{
        "code": "switch_led",
        "type": "Boolean",
        "values": "{}"
      },
      {
        "code": "work_mode",
        "type": "Enum",
        "values": "{\"range\":[\"colour\"]}"
      }
    ]
  }
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining the Latest Device Status

API Description

You can use this API to obtain the latest device status based on the unique ID of the device.

API Address

GET /v1.0/osaas/devices/{device_id}/status

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Array	Result object

Parameters in result

Parameter	Type	Description
code	String	Status code.
value	String	Status value.

Request Example

GET {url}/v1.0/osaas/devices/6c5cc1ce9718d******/status

Success Response Example

{
  "success": true,
  "t": 1545447665981,
  "result": [
    {
      "code": "switch_led",
      "value": "true"
    },
    {
      "code": "work_mode",
      "value": "scene_2"
    }
  ]
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Issuing Device Commands

API Description

You can use this API to issue device commands based on the unique ID of the device.

API Address

POST /v1.0/osaas/devices/{device_id}/commands

Request Parameters

Parameter	Type	Position	Description	Mandatory
device_id	String	URI	Unique ID of a device.	Yes
commands	Arrays	BODY	Command set.	Yes

Parameters in commands

Parameter	Type	Position	Description	Mandatory
code	String	BODY	Function code.	Yes
value	Object	BODY	Function value.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation object

Request Example

POST {url}/v1.0/osaas/devices/6c5cc1ce9718d******/commands

{
  "commands": [
    {
      "code": "switch_led",
      "value": true
    },
    {
      "code": "bright",
      "value": 30
    }
  ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error