TreeApi: API specification

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:

{
  "username": "--username--",
  "password": "--password--"
}

A new token can be retrieved by providing a valid token to GET /security/refresh

Request and response body

Request bodies must be encoded as JSON data. In addition it is required to send the correct HTTP content header field:

Content-Type: application/json

All response bodies are encoded as JSON data too.

Read Item

Retrieve single item values.

HTTP mode

GET

URL

http(s)://<ip or host>:<port>/<item id>

Instead of backslash \ the normal slash / must be used as separator.

URL Parameters

Parameter	Description	Values	Mandatory
light	If activated, only the value of the item is returned. If deactivated, a set of predefined properties are returned.	true/false	No. Default: false
waitForChange	return request on item value change	true/false	No. Default: false
properties	Comma-separated list of item property ids to fetch	<property-id>,<property-id>,…	No. Default: empty

Example

Request:

GET http://127.0.0.1:21012/NETx/VAR/Boolean/Item001?properties=1002,1003,1004

Response:

{
    "itemId": "NETx\\VAR\\Boolean\\Item001",
    "apiPath": "NETx/VAR/Boolean/Item001",
    "parentItemId": "NETx\\VAR\\Boolean",
    "name": "Item001",
    "description": "Variable 1 (Boolean)",
    "type": 21,
    "quality": "uncertain",
    "value": null,
    "lastChange": "2023-05-26T10:05:51.437Z",
    "accessRights": "readWrite",
    "source": "",
    "properties": [
        {
            "id": 1002,
            "name": "Persistent",
            "value": false,
            "unit": ""
        },
        {
            "id": 1003,
            "name": "IsValueSet",
            "value": false,
            "unit": ""
        },
        {
            "id": 1004,
            "name": "Redundant",
            "value": false,
            "unit": ""
        }
    ]
}

Read Multiple Items

To retrieve Retrieve multiple items, the request item Ids must be passed as json array in the request body.

HTTP mode

POST

URL

http(s)://<ip or host>:<port>/read

URL parameters

Parameter	Description	Values	Mandatory
light	If activated, only the value of the item is returned. If deactivated, a set of predefined properties are returned.	true/false	No. Default: false

Request body

["<item id1>", "<item id2", ...]

Example

Request:

http://127.0.0.1:21012/read

[ "NETx/VAR/Boolean/Item001", "NETx/VAR/Boolean/Item002"]

Response:

[
    {
        "itemId": "NETx\\VAR\\Boolean\\Item001",
        "apiPath": "NETx/VAR/Boolean/Item001",
        "parentItemId": "NETx\\VAR\\Boolean",
        "name": "Item001",
        "description": "Variable 1 (Boolean)",
        "type": 21,
        "quality": "uncertain",
        "value": null,
        "lastChange": "2023-05-26T10:05:51.437Z",
        "accessRights": "readWrite",
        "source": ""
    },
    {
        "itemId": "NETx\\VAR\\Boolean\\Item002",
        "apiPath": "NETx/VAR/Boolean/Item002",
        "parentItemId": "NETx\\VAR\\Boolean",
        "name": "Item002",
        "description": "Variable 2 (Boolean)",
        "type": 21,
        "quality": "uncertain",
        "value": null,
        "lastChange": "1899-12-30T00:00:00Z",
        "accessRights": "readWrite",
        "source": ""
    }
]

Read tree recursively

Retrieve current tree state recursively

$ curl -u "usr:passwd" -s http://localhost:21012/tree

URL parameters

Parameter	Description	Mandatory
root	Base item branch (required, eg. NETx/VAR).	Yes.
properties	Comma-separated list of item property ids to fetch.	No. Default: ““
depth	Maximum recursion depth (0=unlimited).	No. Default: 0

Read partial tree recursively

Retrieve multiple tree parts recursively

$ curl -u "usr:passwd" -s -X POST -H "Content-Type: application/json" -d '["NETx/VAR/String/Item001", "NETx/VAR/String/Item002"]' http://localhost:21012/tree

URL parameters

Parameter	Description	Values	Mandatory
properties	Comma-separated list of item property ids to fetch.		No. Default: ““
depth	Maximum recursion depth (0=unlimited).		No. Default: 0

Write Item value

In case the api permission for this item is write-only ('w'), the request returns with HTTP 204

Write single item

$ curl -u "usr:passwd" -s -X POST -H "Content-Type: application/json" -d '"NEW Value for 001"' <http://localhost:21012/NETx/VAR/String/Item001>

Write single item - Retrieve only value of single item

$ 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

http(s)://<ip or host>:<port>/write

URL parameters

None

Request body

[
    {
        "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:

http://127.0.0.1:21012/write

[
    {
        "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:

[
    {
        "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.

ws://localhost:21012/live?items=NETx/VAR/String/Item001,NETx/VAR/String/Item002

URL parameters

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