Using the Shadow API
Using the ShadowAPI as a developer
Table of Contents
Using the ShadowAPIMessage FormatConfigurationExamplesSending a GET request using the mosquitto_pub commandSending a PUT request using the mosquitto_pub command
Using the ShadowAPI
Brief description for the ShadowAPI.
Message Format
In order to issue requests to the internal SIA API via the ShadowAPI, the following JSON message format is required.
{
"uid": "1234431",
"url": "/api/plugins/1/devices/4/...",
"sia_uuid": ["3ce8e232-2b86-41b7-b919-83cbdb67af39", "8ce49732-7ad6-11a1-a219-22efdb82fed5"],
"target": ["publish1", "publish2"]
"method": "GET | POST | PUT | DELETE",
"payload": "{ json... }",
"encode_response": 0,
"headers": {
'Authorization': 'Basic dGVzdHU7dGVzdHA=',
'AppName': 'ShadowAPI',
'x': 'y',
'a': 'b'
},
"status": 200/404...
}The same message format is used also for responses from the MQTT Broker.
| Key | Value | Description |
|---|---|---|
| uid | String | The ID is used to keep track of responses. The ID used in the query request, will be the same in the response result. (optional) |
| url | String | The REST path to the end point where to perform a request. |
| sia_uuid | Array | A list of UUIDs of the targeted SIA. If the first element is "broadcast", then the message will be received by all SIA listening to the topic. |
| target | Array | A list of topics where the results of the query should be published to. |
| method | String | The type of request. It should be either GET, POST, PUT, DELETE |
| payload | String | The payload represents the actual JSON to be sent to the SIA API. Make sure to escape the double quotes ". |
| encode_response | Int | Defines if the payload response from the Shadow API should be URL encoded (optional) |
| header | Object | Header parameters to be sent to used with the SIA API. The 'Authorization' parameter is required. |
| status | Number | Status is ignored for requests, but the answer from a query will contain the request HTTP status code. (optional) |
Configuration
ShadowAPI will look for the following settings in the database:
|
Key Name |
Description |
|---|---|
| shadow_api_broker_url | The URL of the MQTT broker. |
| shadow_api_broker_port | The port of the MQTT broker. |
| shadow_api_broker_username | Username for the MQTT broker. |
| shadow_api_broker_password | Password for the MQTT broker. |
| shadow_api_broker_subscription_topics | List of topics to subscribe to. Multiple values allowed, comma separated. |
Those settings can also be set using the web interface on SIA, by navigating to the Tools menu, under the ShadowAPI section.
The username and password fields for the MQTT broker are not required.
Examples
The examples below, make use of the mosquitto message broker and related helper tools (https://mosquitto.org/).
Sending a GET request using the mosquitto_pub command
mosquitto_pub -h localhost -p 4000 -t query -m
'{
"uid": "170",
"url": "/api/plugins/6/devices/1/items/1/data",
"sia_uuid": "43a3b04a-2526-4723-123e-ebcf43b0886c",
"target": ["topic5", "result", "group2"],
"method": "GET",
"encode_response": 0,
"payload": "none",
"headers": {"Authorization": "Basic dGVzdHU7dGVzdHA=", "AppName": "ShadowAPI"},
"status": ""
}'
-u testu -P testpHere, the MQTT Broker address is localhost on port 4000. The message is published on the "query" topic.
The message has an ID of 170 (arbitrarily chosen based on the client side posting the requests). The url is the end point where to perform the GET request (defined by method). The sia_uuid is the UUID of the SIA where the data is stored. Target contains the list of topics (topic5, result and group2) where the results of the query will be posted. The payload parameter is not needed for the specific GET request and it is not used. The Headers parameter contains the Authorization token for the basic auth on SIA. Finally, testu and testp are the credentials for the MQTT broker.
Sending a PUT request using the mosquitto_pub command
mosquitto_pub -h localhost -p 4000 -t query -m
'{
"uid": "310",
"url": "/api/plugins/6/devices/1/items/1/write",
"sia_uuid": "43a3b04a-2526-4723-123e-ebcf43b0886c",
"target": ["result", "group2"],
"method": "PUT", "payload":
"{\"value\": \"1234\"}",
"headers": {"Authorization": "Basic dGVzdHU7dGVzdHA=", "AppName": "ShadowAPI"},
"status": ""
}' -u testu -P testpSimilar to the previous GET request, with the difference of the payload which is a JSON string setting the value "1234" on the specific device/item defined by the end point (URL). Please notice how the double quotes are escaped in the payload.