# Shadow Service

You can create the IoT application based on the Shadow Service APIs.

# API List

URLMethodDescription
/shadowsPOSTCreate a shadow model
/shadowsGETGet the list of shadow models
/shadows/${shadow_id}GETGet the specified shadow model’s properties
/shadows/${shadow_id}PUTUpdate the specified shadow model’s properties
/shadows/${shadow_id}DELETEDelete the specified shadow model
/shadows/${shadow_id}/jsonGETGet the specified shadow model’s JSON
/shadows/${shadow_id}/jsonPUTUpdate the specified shadow model’s JSON entirely
/shadows/${shadow_id}/jsonPATCHUpdate the specified shadow model’s JSON partially

# Get the list of shadow models

# URL

GET /shadows

# Request

ParamsTypeDescription
_pageIntegerPage number
_limitIntegerNumber of items displayed each page

# Response

KeyTypeDescription
itemsArray of ObjectsObjects of shadow models
items[].descriptionStringDescription of shadow models
items[].updatedAtStringUpdate time of shadow models (UTC)
items[].shadowIDStringID of shadow models
items[].createdAtStringCreate time of shadow models (UTC)
items[].shadowNameStringName of shadow models
metaObjectObject of pagination
meta.pageIntegerPage Number
meta.limitIntegerNumber of items displayed each page
meta.countIntegerItem Number

# Request Example

curl -u app_id:app_secret -X GET {api}/shadows/?_page=1&_limit=10
1

# Response Example

{
  "items": [
    {
      "description": "123", 
      "updatedAt": "2022-06-10 03:20", 
      "shadowID": "test_shadow", 
      "createdAt": "2022-06-10 03:20", 
      "shadowName": "test"
    }
  ], 
  "meta": {
    "limit": 10, 
    "page": 1, 
    "count": 1
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Get the specified shadow model’s properties

# URL

GET /shadows/${shadow_id}

# Request

[none]

# Response

KeyTypeDescription
descriptionStringDescription of shadow models
updatedAtStringUpdate time of shadow models (UTC)
shadowIDStringID of shadow models
createdAtStringCreate time of shadow models (UTC)
shadowNameStringName of shadow models

# Request Example

curl -u app_id:app_secret -X GET {api}/shadows/${shadow_id}
1

# Response Example

{
  "description": "123", 
  "updatedAt": "2022-06-10 03:20", 
  "shadowID": "test_shadow", 
  "createdAt": "2022-06-10 03:20", 
  "shadowName": "test"
}
1
2
3
4
5
6
7

# Get the specified shadow model’s JSON

# URL

GET /shadows/${shadow_id}/json

# Request

[none]

# Response

KeyTypeDescription
createdAtIntegerTimestamp of shadow service JSON created (UTC)
lastTimeIntegerTimestamp of shadow service JSON published (UTC)
versionIntegerVersion of shadow service JSON
dataStringPayload

# Response Format Example

KeyTypeDescription
data[].colorStringcolor
data[].stateIntegerstate
data[].powerIntegerelectricity capacity

# Request Example

curl -u app_id:app_secret -X GET {api}/shadows/${shadow_id}/json
1

# Response Example

{
  "data": {
    "color": "blue", 
    "power": 0, 
    "state": 1
  }, 
  "createAt": 1660618831979, 
  "lastTime": 1660631951790, 
  "version": 1
}
1
2
3
4
5
6
7
8
9
10

# Create a shadow model

# URL

POST /shadows

# Request

ParamsTypeDescription
descriptionStringDescription of shadow models
shadowIDStringID of shadow models
shadowNameStringName of shadow models

Tip

ID of shadow models is optional, the system will automatically generate one.

# Response

KeyTypeDescription
descriptionStringDescription of shadow models
updatedAtStringUpdate time of shadow models (UTC)
shadowIDStringID of shadow models
createdAtStringCreate time of shadow models (UTC)
shadowNameStringName of shadow models

# Request Example

curl -u app_id:app_secret -X POST -d '{"description": "123","shadowID": "test_shadow","shadowName": "test"}' {api}/shadows
1

# Response Example

{
  "description": "123", 
  "updatedAt": "2022-06-10 03:39", 
  "shadowID": "test_shadow", 
  "createdAt": "2022-06-10 03:39", 
  "shadowName": "test"
}
1
2
3
4
5
6
7

# Update the specified shadow model’s properties

# URL

PUT /shadows/${shadow_id}

# Request

ParamsTypeDescription
descriptionStringDescription of shadow models
shadowNameStringName of shadow models

Tip

The ID of shadow model can't be modified once it's created.

# Response

KeyTypeDescription
descriptionStringDescription of shadow models
updatedAtStringUpdate time of shadow models (UTC)
shadowIDStringID of shadow models
createdAtStringCreate time of shadow models (UTC)
shadowNameStringName of shadow models

# Request Example

curl -u app_id:app_secret -X PUT -d '{"description": "","shadowName": "test"}' {api}/shadows/${shadow_id}
1

# Response Example

{
  "description": "", 
  "updatedAt": "2022-06-10 03:39", 
  "shadowID": "test_shadow", 
  "createdAt": "2022-06-10 03:39", 
  "shadowName": "test"
}
1
2
3
4
5
6
7

# Update the specified shadow model’s JSON entirely

# URL

PUT /shadows/${shadow_id}/json

# Request

ParamsTypeDescription
dataStringPayload

# Request Format Example

ParamsTypeDescription
data[].colorStringcolor
data[].stateIntegerstate
data[].powerIntegerelectricity capacity

# Response

KeyTypeDescription
createdAtIntegerTimestamp of shadow service JSON created (UTC)
lastTimeIntegerTimestamp of shadow service JSON published (UTC)
versionIntegerVersion of shadow service JSON
dataStringPayload

# Request Example

curl -u app_id:app_secret -X PUT -d '{"color": "blue","state": 1,"power": 0}' {api}/shadows/${shadow_id}/json
1

# Response Example

{
  "data": {
    "color": "blue", 
    "power": 0, 
    "state": 1
  }, 
  "createAt": 1660618831979, 
  "lastTime": 1660631951770, 
  "version": 9
}
1
2
3
4
5
6
7
8
9
10

# Update the specified shadow model’s JSON partially

# URL

PATCH /shadows/${shadow_id}/json

# Request

ParamsTypeDescription
dataStringPayload

# Request Format Example

ParamsTypeDescription
data[].specsIntegerspecification

# Response

KeyTypeDescription
createdAtIntegerTimestamp of shadow service JSON created (UTC)
lastTimeIntegerTimestamp of shadow service JSON published (UTC)
versionIntegerVersion of shadow service JSON
dataStringPayload

# Request Example

curl -u app_id:app_secret -X PATCH -d '{"specs": 2}' {api}/shadows/${shadow_id}/json
1

# Response Example

{
  "data": {
    "color": "blue", 
    "power": 0, 
    "specs": 2, 
    "state": 1
  }, 
  "createAt": 1660618831979, 
  "lastTime": 1660631880990, 
  "version": 10
}
1
2
3
4
5
6
7
8
9
10
11

# Update a multi-level object level by level

# URL

PATCH /shadows/${shadow_id}/json

# Request

ParamsTypeDescription
dataStringPayload

# Response

KeyTypeDescription
createdAtIntegerTimestamp of shadow service JSON created (UTC)
lastTimeIntegerTimestamp of shadow service JSON published (UTC)
versionIntegerVersion of shadow service JSON
dataStringPayload

# Request Example

Tip

If you need to update a multi-level object incrementally, please update level by level. Do not add a multi-level object directly, it will return an error.

# Wrong Request Example
curl -u app_id:app_secret -X PATCH -d '{"key": {"a":100}}' {api}/shadows/${shadow_id}/json
1
2
# Good Request Example
curl -u app_id:app_secret -X PATCH -d '{"key": {}}' {api}/shadows/${shadow_id}/json

curl -u app_id:app_secret -X PATCH -d '{"key": {"a":100}}' {api}/shadows/${shadow_id}/json
1
2
3
4

# Response Example

{
  "data": {
    "color": "blue",
    "key": {},
    "power": 0,
    "specs": 2,
    "state": 1
  },
  "createAt": 1662087412285,
  "lastTime": 1662106829205,
  "version": 12
}
1
2
3
4
5
6
7
8
9
10
11
12
{
    "data": {
        "color": "blue",
        "key": {
            "a": 100
        },
        "power": 0,
        "specs": 2,
        "state": 1
    },
    "createAt": 1662087412285,
    "lastTime": 1662106900812,
    "version": 13
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Delete the specified shadow model

# URL

DELETE /shadows/${shadow_id}

# Request

[none]

# Response

[none]

# Request Example

curl -u app_id:app_secret -X DELETE {api}/shadows/${shadow_id}
1