Introduction

This document provides a simple overview of the TREE API and how it can be used. It is intended for users who want to understand how to interact with the system. This document also includes sample requests and responses to help you get started quickly.

What is TREE API?

The TREE API, a feature of the NETx BMS platform, is an interface that allows external applications (such as web apps, mobile apps, or other systems) to communicate with the server and access structured data in a tree format.

Think of it like a hierarchical structure (like folders and subfolders on your computer)

The TREE API works using a simple request and response process:

Request is sent
Your system sends a request to the TREE API (for example, asking for data or sending new data).
Processing
The TREE system receives the request and processes it.
Response is returned
The API sends back a response with the result (data, success message, or error).

How TREE API Works (Step-by-Step)

1. Client Sends a Request

An external system (client) sends a request to the server using HTTP/HTTPS.

This request is usually sent using:

GET → to read data
POST → to send or update data

2. Authentication (Security Layer)

Before giving access, the API checks:

Username / Password or API key
Token (in some setups)

This ensures only authorized users can access the system.

3. API Processes the Request

Once authenticated, the server:

Understands the request (endpoint + parameters)
Finds the requested node in the tree structure
Collects required data (like device status, values, etc.)

4. Data is Organized in Tree Format

The system stores data like this:

Building
├── Floor 1
│ ├── Room A
│ │ ├── Temperature Sensor
│ │ └── Light Status
│ └── Room B
└── Floor 2

Each item is called a node, and each node has:

ID
Name
Type
Value (if applicable)

5. API Sends Response (JSON Format)

The server sends back the response in JSON format (standard for APIs).

Example:

{
  "id": "123",
  "name": "Temperature Sensor",
  "value": "24°C",
  "children": []
}

This format is easy for any application to read and use.

6. Client Uses the Data

The client application:

Displays data (dashboard, UI)
Stores it
Uses it for automation, alarms, or analytics

Real-Time Example with Actual Setup

Let’s move to a practical example that we have prepared using the NETx BMS platform and the Postman application. In this setup, NETx acts as the client, while Postman acts as the server. we have demonstrated both GET and POST methods. Currently, we are using localhost, so the URL is based on the local system. (Note: If the workspace is hosted on the cloud, the URL should be taken from the cloud path.)

Configure Tree API Interface

Enter API IP Address, here I am using my local PC hence it is 127.0.0.1

Knowledge base link- https://netxautomation.atlassian.net/wiki/x/MABjXg

Configure TreeAPI User definition

User definitions ensure this access is secure and controlled.

Knowledge base link- https://netxautomation.atlassian.net/wiki/x/TgBjXg

TreeApi permission definitions

Tree API Permission Definitions specify what actions a user can perform and which parts of the NETx item tree they are allowed to access when using the Tree API.

Knowledge base link- https://netxautomation.atlassian.net/wiki/x/bgBjXg

Note- Note: '*' means access is granted to the entire Item Tree. The user can limit the access as required.

After this configuration restart server

Name of Item IDs are accessing - NETx\VIRTUAL\WingA\Floor1\Room1001\DoNotDisturb

How to read the Server data (GET Method) on Postman

Endpoint URL- http://localhost:21012/<ItemIdPath>

Example URL: http://localhost:21012/NETx\VIRTUAL\WingA\Floor1\Room1001\DoNotDisturb

Postman Result:

How to write the Server data (POST Method) on Postman

http://localhost:21012/write

Body

Note- 2 backslash is mandatory in the Item ID when writing value.