# API Documentation

## 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**

   <figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2Fu5w46lEPPTsCmKdM7RBj%2Fimage.png?alt=media&#x26;token=6cad50bb-95b7-4a3c-be6e-e5c6d5297a53" alt=""><figcaption><p>Click on the Check License info</p></figcaption></figure>

   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.

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2FAM7ix3mVDNxaH5klKM4l%2Fimage.png?alt=media&#x26;token=98474671-0a10-4663-8b54-64b386e52e39" alt=""><figcaption></figcaption></figure>

2. Create an API User

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

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2F2tkJYWU2Mt3sTAYImheE%2Fimage.png?alt=media&#x26;token=494b7909-1033-4a10-b599-046f33fabbed" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2FYvcUinNtkgQPaMzbu5ol%2Fimage.png?alt=media&#x26;token=6cb70fce-ff77-4307-8ab1-71653f81b60a" alt=""><figcaption><p>Add User Window</p></figcaption></figure>

Fill in all the fields:&#x20;

**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.

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2Fsui94CXeCdygn0vIz7ji%2Fimage.png?alt=media&#x26;token=1370ee3a-7568-4c55-92b9-477d6e63621f" alt=""><figcaption><p>Sample configuration</p></figcaption></figure>

Click on **CREATE** button to finish.

## API Configuration

{% hint style="info" %}
The API uses basic authentication, which uses a username and password created in the ObX Admin Tools.
{% endhint %}

### API Endpoint

```javascript
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/
*/


```

***

```javascript
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](http://www.domain.com)

### Query Paremeters

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

```javascript
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.
```

```javascript
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.
```

```javascript
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*/
```

```javascript
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.&#x20;

### Example Using Postman

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2FcfmL81FIRxFNoIalalGs%2Fimage.png?alt=media&#x26;token=229fb4d0-14b8-461b-92f6-05e8d1c56bbe" alt=""><figcaption><p>Postman Settings</p></figcaption></figure>

URL:

```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:&#x20;

<figure><img src="https://1616126851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk102NjXt3SLqrvAU01VG%2Fuploads%2FIiFml5SEdmIhjAsI8N1Z%2Fimage.png?alt=media&#x26;token=3f7d8acd-01ab-4a47-9bbe-78fe1c9827e3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note that in Authentication, you have to use the Basic Auth and use the credentials created in the ObX Admin Tools.
{% endhint %}

#### Output Response:

```json
{
    "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.

{% hint style="info" %}
Notice the timestamp format is in ISO806.
{% endhint %}

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
```

{% hint style="warning" %}
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.
{% endhint %}

### Example Using NodeJS

Using **axios** library (but you can use any libraries)

```javascript
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);
});

```
