1 Breaking changes to version >= 1.1.2
2 Authentication
- 2.1 Basic authentication
- 2.2 JWT authentication
3 Request and response format
4 Services for reading and writing items
- 4.1 Read Item
- 4.2 Read Multiple Items
- 4.3 Read tree recursively
- 4.4 Read partial tree recursively
- 4.5 Write Item value
- 4.6 Write Multiple Items
- 4.7 Set Multiple Items
5 Listen for item value changes
- 5.1 URL parameters

Breaking changes to version >= 1.1.2

WithTreeApi version 1.1.2, there are some changes in the API that may break your application. Before upgrading, please read these changes and adapt your application:

Write Multiple Items: Write requests are now used instead of set requests.
Before 1.1.2, this request is issuing set requests to the items in Core Server. Set requests are not forwarded to the underlying field bus. Therefore, the requests to the Core Server are changed to write requests. If you sill want to use set requests instead of writes requests, please use the new API call Set Multiple Items.
Write Multiple Items: the timestamp parameter is no longer available since write requests are always sent at the current point in time. If you want to set the timestamp of items, use the API call Set Multiple Items.
Write Item: no values are now returned. The API call is responded with HTTP 204 if it was successul.
For physical data points, write requests are sent to the field level. The item value is only updated by the feedback from the field level. The time between the write requests and receiving the feedback depends on the field bus protocol (e.g. for Modbus it can be a full polling cycle). Therefore it does not make sense to give the current value back.
Set Multiple Items: new API call added.

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--"
}

The response contains the token and the expiration timestamp in the JSON body:

{
    "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImFkbWluIiwiSWQiOiJlN2I2ZGY1ZS1lYjA5LTQ2MmEtODllYy02ODAyZjJmZGQ3YjIiLCJqdGkiOiJkMjI1M2Y2YS04M2EwLTRiODItOGZmOC02ZDdhYzIwZDI1NDIiLCJuYmYiOjE3NDAxNDIxODksImV4cCI6MTc0MDE0NTc4OSwiaWF0IjoxNzQwMTQyMTg5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjIxMDEyIiwiYXVkIjoiaHR0cDovLzEyNy4wLjAuMToyMTAxMiJ9.RDCW_auuKsSRscdl1knpAcHw7BX09T6vG8qkOtlMnaYFMTm0VDVmd3eFRztsxaTsLqicn8hYsTrWYNKdOjzQfw",
    "expiration": "2025-02-21T13:49:49Z"
}

The token must be added in the HTTP header for each further request. Use the header “Authorization” to add the token to the header.

Before the token expires, a new one must be retrieved. This can done by send a refresh request via 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:

Content-Type: application/json

All response bodies are encoded as JSON data too.

Services for reading and writing items

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

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

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	Values	Mandatory

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

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

This request returns with HTTP 204 if successful.

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 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>,
        "source": <source information>
    },
    {
        "itemId": "<item id 2>",
        "value": <value>,
        "source": <source information>
    },
    ...
]

itemId: mandatory
value: mandatory
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,
        "source": "SYS:TREEAPI"
    },
    {
        "itemId": "NETx\\Virtual\\Floor1\\Meter01\\Total Energy",
        "value": 130.5,
    },
	{
        "itemId": "NETx\\Virtual\\Floor1\\Meter02\\Total Energy",
        "value": 133.5,
    },
	{
        "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"
    }
]

Set Multiple Items

To set multiple item values, 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>/set

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

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

TreeApi: API specification

Breaking changes to version >= 1.1.2

Authentication

Basic authentication

JWT authentication

Request and response format

Services for reading and writing items

Read Item

Read Multiple Items

Read tree recursively

Read partial tree recursively

Write Item value

Write Multiple Items

Set Multiple Items

Listen for item value changes

URL parameters