| Table of Contents |
|---|
Authentication
For each request, authentication data must be sent. For the TreeApi, two kinds of authentication are possible: basic authentication and JWT authentication.
Basic authentication
If basic authentication is used, the user name and password must be encoded in the basic authentication header field of the HTTP request. This must be done for each request.
JWT authentication
JWT config options can be set in xio.TreeApi.cfg
A Bearer token can be retrieved via POST /security/createToken
Body:
...
A new token can be retrieved by providing a valid token to GET /security/refresh
Request and response
...
format
Request bodies must be encoded as JSON data. In addition it is required to send the correct HTTP content header field:
...
All response bodies are encoded as JSON data too.
Services for reading and writing items
Read Item
Retrieve single item values.
...
| Code Block |
|---|
$ curl -u "usr:passwd" -s -X POST -H "Content-Type: application/json" -d '"NEW Value for 001"' <http://localhost:21012/NETx/VAR/String/Item001?light=true> |
Write Multiple Items
To write multiple items, the item Ids including the values and optionally the timestamps must be passed as JSON array in the request body.
HTTP mode
POST
URL
| Code Block |
|---|
http(s)://<ip or host>:<port>/write |
URL parameters
None
Request body
| Code Block |
|---|
[
{
"itemId": "<item id 1>",
"value": <value>,
"timestamp": <timestamp>,
"source": <source information>
},
{
"itemId": "<item id 2>",
"value": <value>,
"timestamp": <timestamp>,
"source": <source information>
},
...
] |
itemId: mandatory
value: mandatory
timestamp: optional
source: optional
If not used, use: “SYS:TREEAPI;IP:<client IP>;USR:<username>”
Example
Request:
| Code Block |
|---|
http://127.0.0.1:21012/write |
| Code Block |
|---|
[
{
"itemId": "NETx\\Virtual\\Floor1\\Meter01\\Total Energy",
"value": 128.8,
"timestamp": "2024-02-1T00:00:00.00Z",
"source": "SYS:TREEAPI"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter01\\Total Energy",
"value": 130.5,
"timestamp": "2024-02-1T01:15:00.00Z"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter02\\Total Energy",
"value": 133.5,
"timestamp": "2024-02-1T01:15:00.00Z"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter02\\Volts",
"value": 223.45
}
] |
Response:
| Code Block |
|---|
[
{
"itemId": "NETx\\Virtual\\Floor1\\Meter01\\Total Energy",
"result": "success"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter01\\Total Energy",
"result": "success"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter02\\Total Energy",
"result": "success"
},
{
"itemId": "NETx\\Virtual\\Floor1\\Meter02\\Volts",
"result": "success"
}
] |
Listen for item value changes
Make sure to include the 'Authorization' header based on your chosen settings.
...
Parameter | Description | Values | Mandatory |
|---|---|---|---|
items | Comma-separated list of item property ids to watch. | Comma-separated list of item property ids. | No. Default ““. |
URL parameters
items | comma-separated list of item property ids to watch |