Information about the states of user devices

Requests information about the state of user devices.

Example situation when the current request is sent: the user opens the  Yango Play app and wants to change the state of their devices.

In response to the request, the provider must return the states of the requested user devices.

Note.

The capabilities for which the state request is not available (with retrievable=false). Can be omitted in the response because their state is ignored.

  1. Smart home platform request format
  2. Provider response format
  3. Example

Smart home platform request format

Yango Smart Home sends a request to the provider's Endpoint URL (https://example.com/).

POST https://example.com/v1.0/user/devices/query

Request headers

Header Description Required
Authorization User's authorization token. Yes
Content-Type The format of sent/submitted data. Possible values: application/json. Yes, in operations with HTTP POST
X-Request-Id Request ID. Must be logged on the provider's side for investigating incidents and problems. Yes
Header Description Required
Authorization User's authorization token. Yes
Content-Type The format of sent/submitted data. Possible values: application/json. Yes, in operations with HTTP POST
X-Request-Id Request ID. Must be logged on the provider's side for investigating incidents and problems. Yes

Request body format

{
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
}
Parameter Type Description Required
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
custom_data Object An object passed by the provider for the device in response to the request Information about user devices. No
Parameter Type Description Required
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
custom_data Object An object passed by the provider for the device in response to the request Information about user devices. No

Provider response format

The provider must use the correct format to respond to the request received from Yango Smart Home.

HTTP/1.1 200 OK

{
  "request_id": String,
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ],
        "properties": [
          "<property1>": Object,
          "<property2>": Object,
          ...
        ],
        "error_code": String,
        "error_message": String
      },
      ...
    ]  
  }
}
Parameter Type Description Required
request_id String Request ID. Yes
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
capabilities Array of objects Array with information about device capabilities. No
properties Array of objects Array with information about the device's properties. No
error_code String An error code from the list. If the field is filled in, the capabilities and properties parameters are ignored. No
error_message String Extended human-readable description of a possible error. Available only on the Testing tab of the developer console. No
capabilities object
<capability1> Object Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities. No
properties object
<property1> Object Property and its status. For a more detailed list of available properties and their parameters, see About properties. No
<property2> Object Property and its status. For a more detailed list of available properties and their parameters, see About properties. No
Parameter Type Description Required
request_id String Request ID. Yes
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
capabilities Array of objects Array with information about device capabilities. No
properties Array of objects Array with information about the device's properties. No
error_code String An error code from the list. If the field is filled in, the capabilities and properties parameters are ignored. No
error_message String Extended human-readable description of a possible error. Available only on the Testing tab of the developer console. No
capabilities object
<capability1> Object Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities. No
properties object
<property1> Object Property and its status. For a more detailed list of available properties and their parameters, see About properties. No
<property2> Object Property and its status. For a more detailed list of available properties and their parameters, see About properties. No

Codes associated with the request

Example

This example describes the properties of a lamp featuring color and outlet control.

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Request body

{
    "devices": [
        {
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            } 
        },
        {
            "id": "sock-56GF-3" 
        }   
    ]
}