API Documentation

This page explain how you can configure and send API request to read data from the ObX Historian Server.

Pre-Requisites

1. The ObX Historian Server has API License.

   You can check if you have API license using ObX Admin Tools, from the Main page, click on the Check License Info

   

   Click on the Check License info

   This will open a License Viewer dialog in which you can see all list of features license to you ObX Historian Server. Make sure the API license is checked, it means you have API license.

1. Create an API User

Open ObX Admin Tools and from the left pane Go to -> Users -> API

Right-click on the API -> Add User , this will open a new window for creating a User in the ObX historian.

Add User Window

Fill in all the fields:

Username (required) - the username used by the 3rd party software to connect.

Password (required) - the password used by the 3rd party software to connect.

Confirm (required) - for password confirmation.

Description (optional)

Grant - Check this where you want to give this API user an access to specific datasource.

Privilege - Select what type of privilege this API user will have to specific datasource, for example READ - for read only, WRITE - for write only, ALL - for both read and write.

Sample configuration

Click on CREATE button to finish.

API Configuration

The API uses basic authentication, which uses a username and password created in the ObX Admin Tools.

API Endpoint

https://{IP Address}/db/
/** https for secured connections
*Take note that the certificate used is a self-signed certificate
*/

/*Example use when IP Address = 172.17.1.64 
  endpoint will be https://172.17.1.64/db/
*/

---

http://{IP Address}/db
/**
* http for insecure connections
*/

IP Address - the IP address where the ObX WebUI component is installed. It could also be a valid FQDN e.g. www.domain.com

Query Paremeters

• q : The query (SQL like) to fetch data in the ObX Historian.

SELECT mean("value") FROM "Tag1" WHERE time >=now()-5m GROUP BY time(1m) tz('Asia/Singapore'); 
// This query return the average/mean value of Tag1 for the last 5minutes sampled every 1 minute of data.
// The tz is your current timezone, this is necessary to avoid time region confusion.

SELECT "value" FROM "Tag1" WHERE time >=now()-1m ORDER BY time DESC LIMIT 1;
// This query return the last or current value of the Tag.

SELECT "value" FROM "Tag1" WHERE time >=now()-1m
/* This query returns all the values - raw value without sampling for the last 1 minute of data*/

SELECT mean("value") FROM "Tag1" WHERE time >=1726651500000ms and time <=1726652100000ms GROUP BY time(1m) tz('Asia/Singapore)
/*This query return average/mean value of Tag1 between 2024-09-18 17:25:00 and 2024-09-18 17:35:00
Notice that the time accepted by the API is a milliseconds Unix epoch timestamp, so 
you need to convert your time in ms. */

/*Using nodeJS or Javascript you can simply */
startTime = new Date('2024-09-18 17:25:00).getTime() // to get the Unix epoch timestamp

• db: The datasource name in the ObX Historian.

Example Using Postman

Postman Settings

URL:

https://localhost/db/

Query Parameters:

Query Parameters	Value
q	SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m)
db	Energy

Authentication:

Note that in Authentication, you have to use the Basic Auth and use the credentials created in the ObX Admin Tools.

Output Response:

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "Counter",
                    "columns": [
                        "time",
                        "mean"
                    ],
                    "values": [
                        [
                            "2024-09-18T09:25:00Z",
                            98.11111111111111
                        ],
                        [
                            "2024-09-18T09:26:00Z",
                            29.5
                        ],
                        [
                            "2024-09-18T09:27:00Z",
                            57.857142857142854
                        ],
                        [
                            "2024-09-18T09:28:00Z",
                            48.5
                        ],
                        [
                            "2024-09-18T09:29:00Z",
                            44.621848739495796
                        ],
                        [
                            "2024-09-18T09:30:00Z",
                            67.5
                        ],
                        [
                            "2024-09-18T09:31:00Z",
                            31.403361344537814
                        ],
                        [
                            "2024-09-18T09:32:00Z",
                            59.49579831932773
                        ],
                        [
                            "2024-09-18T09:33:00Z",
                            45.30252100840336
                        ],
                        [
                            "2024-09-18T09:34:00Z",
                            46.583333333333336
                        ],
                        [
                            "2024-09-18T09:35:00Z",
                            64.34453781512605
                        ],
                        [
                            "2024-09-18T09:36:00Z",
                            33.6
                        ],
                        [
                            "2024-09-18T09:37:00Z",
                            61.33613445378151
                        ],
                        [
                            "2024-09-18T09:38:00Z",
                            42.5
                        ],
                        [
                            "2024-09-18T09:39:00Z",
                            48.94117647058823
                        ],
                        [
                            "2024-09-18T09:40:00Z",
                            61.5
                        ],
                        [
                            "2024-09-18T09:41:00Z",
                            35.80672268907563
                        ],
                        [
                            "2024-09-18T09:42:00Z",
                            63.666666666666664
                        ],
                        [
                            "2024-09-18T09:43:00Z",
                            39.61344537815126
                        ],
                        [
                            "2024-09-18T09:44:00Z",
                            50.68333333333333
                        ],
                        [
                            "2024-09-18T09:45:00Z",
                            58.67226890756302
                        ],
                        [
                            "2024-09-18T09:46:00Z",
                            37.7
                        ],
                        [
                            "2024-09-18T09:47:00Z",
                            65.6218487394958
                        ],
                        [
                            "2024-09-18T09:48:00Z",
                            36.5
                        ],
                        [
                            "2024-09-18T09:49:00Z",
                            53.03361344537815
                        ],
                        [
                            "2024-09-18T09:50:00Z",
                            55.5
                        ],
                        [
                            "2024-09-18T09:51:00Z",
                            39.75
                        ],
                        [
                            "2024-09-18T09:52:00Z",
                            67.94957983193277
                        ],
                        [
                            "2024-09-18T09:53:00Z",
                            33.5
                        ],
                        [
                            "2024-09-18T09:54:00Z",
                            54.529411764705884
                        ],
                        [
                            "2024-09-18T09:55:00Z",
                            52.5
                        ],
                        [
                            "2024-09-18T09:56:00Z",
                            42.04201680672269
                        ],
                        [
                            "2024-09-18T09:57:00Z",
                            69.81666666666666
                        ],
                        [
                            "2024-09-18T09:58:00Z",
                            30.3781512605042
                        ],
                        [
                            "2024-09-18T09:59:00Z",
                            56.833333333333336
                        ],
                        [
                            "2024-09-18T10:00:00Z",
                            49.35294117647059
                        ],
                        [
                            "2024-09-18T10:01:00Z",
                            43.85
                        ],
                        [
                            "2024-09-18T10:02:00Z",
                            68.5
                        ],
                        [
                            "2024-09-18T10:03:00Z",
                            31.092436974789916
                        ],
                        [
                            "2024-09-18T10:04:00Z",
                            58.88333333333333
                        ],
                        [
                            "2024-09-18T10:05:00Z",
                            46.563025210084035
                        ],
                        [
                            "2024-09-18T10:06:00Z",
                            45.9
                        ],
                        [
                            "2024-09-18T10:07:00Z",
                            65.4873949579832
                        ],
                        [
                            "2024-09-18T10:08:00Z",
                            32.916666666666664
                        ],
                        [
                            "2024-09-18T10:09:00Z",
                            60.621848739495796
                        ],
                        [
                            "2024-09-18T10:10:00Z",
                            43.5
                        ],
                        [
                            "2024-09-18T10:11:00Z",
                            48.09243697478992
                        ],
                        [
                            "2024-09-18T10:12:00Z",
                            62.5
                        ],
                        [
                            "2024-09-18T10:13:00Z",
                            34.96666666666667
                        ],
                        [
                            "2024-09-18T10:14:00Z",
                            62.94117647058823
                        ],
                        [
                            "2024-09-18T10:15:00Z",
                            40.5
                        ],
                        [
                            "2024-09-18T10:16:00Z",
                            49.99152542372882
                        ],
                        [
                            "2024-09-18T10:17:00Z",
                            59.5
                        ],
                        [
                            "2024-09-18T10:18:00Z",
                            36.97478991596638
                        ],
                        [
                            "2024-09-18T10:19:00Z",
                            65.03333333333333
                        ],
                        [
                            "2024-09-18T10:20:00Z",
                            37.5
                        ],
                        [
                            "2024-09-18T10:21:00Z",
                            51.80672268907563
                        ],
                        [
                            "2024-09-18T10:22:00Z",
                            56.5
                        ],
                        [
                            "2024-09-18T10:23:00Z",
                            38.08474576271186
                        ],
                        [
                            "2024-09-18T10:24:00Z",
                            67.08333333333333
                        ],
                        [
                            "2024-09-18T10:25:00Z",
                            31.038095238095238
                        ]
                    ]
                }
            ]
        }
    ]
}

The output response is in JSON format.

Notice the timestamp format is in ISO806.

You can also simply use a web browser and type in directly into URL

https://localhost/db?q=SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m)&db=Energy

If you are using a NodeJS or any framework to connect to the API, make sure the disable the tls verification, the API uses a self-signed-certificates, by default all frameworks verifies this and interrupts all connection with a self-signed-certificates.

Example Using NodeJS

Using axios library (but you can use any libraries)

const axios = require('axios');
const https = require('https');

// Disable TLS verification
const agent = new https.Agent({
  rejectUnauthorized: false,
});

// Send the GET request
axios.get('https://localhost/db', {
  params: {
    q: 'select "value" from "Counter" Where time >=now()-1m',
    db: 'Energy',
  },
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from('your-username:your-password').toString('base64'), // Replace with your credentials
  },
  httpsAgent: agent,  // Set the custom HTTPS agent
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error);
});