Introduction

Integration

This document focuses on one of Pani’s data connectivity options, REST API integration. This integration technique allows your site’s IT department to select and control what data is sent to Pani and when.

 

The three, high-level steps involved in this process are outline in the diagram below. The steps are:

1. Consolidation
   • A member of your team writes a script to query your local data stores.
2. Integration
   • The consolidated data is pushed to Pani via REST API integration.
3. Service Usage
   • Pani’s system processes your data and presents an interface for analyzing your ingested data alongside derived process intelligence.

 

Fig. 1 REST API Data Integration

Rest API

The following sections provide information about how the API functions and is for anyone that has basic experience with consuming an HTTP API.  These are the specifics for setting up:

 

Getting Started

The structure of a valid HTTP request to our API for data integration consist of the following:

• Method
• URL
• Headers (Authorization/ Content type)
• Payload

Request are made using standard HTTP requests. All responses are returned in JSON format (JavaScript Object Notation).

 
To use the API, additional setup is required with Pani’s CS team to ensure configuration is complete prior to data being submitted to our data servers. Contact [email protected] for details on access.
API request must conform to the following specification.

Method

Method refers to the HTTP request type for this, use POST.

 

 

URL

URL refers to the ingress Uniform Resource Locator at:

 

 

Headers

 

Basic Authorization

All requests are authorized using HTTP basic access authentication (Basic Auth). A request contains header field authorization details, where “credentials” represents the Base64 encoding of ID and password joined by a single colon.

 

 

Pani will encode the credentials directly and provide them to you.

 

NOTE: Some applications may request unique password and ID fields. If this is the case, you will need to decode the credentials provided by Pani. Free utilities/sites such as https://www.base64decode.org/ allow you to paste the Pani credentials into the site and extract the username and password.

 

Content Type
This HTTP header field describes the content type which describes the application. This must be specified as JSON, as we only accept this for formatted payloads.

 

 

Payload

 

The request payload must conform to the following:

• Must be in JSON format.
• Must include a “deviceId” field with a JSON string value. 
• Must include a “timestamp” field whose value is an ISO 8601-formatted JSON string.
• All fields other than "deviceId" and "timestamp" represent sensor readings or tags, and their values must be numeric and in the JSON format. Unlike deviceId and timestamp, sensor/tag values are not enclosed in quotes.

 

{
       "deviceId": "string",
       "timestamp": "string (iso8601 format)",
       "tag1": val1 (number),
       "tag2": val2 (number),
       "tag3": val2 (number)
 }

 

Null Values
There may be situations where you may want to use a null value, such as when a system is offline with no data versus a value of zero, which is a valid value. The Tag name must be in quotes, and the tag value must be a numeric value or the word null, none of them in quotes, and conforming to the payload formatting. 

 

 

NOTE: Multiple tags can be passed in a payload, and multiple timestamps can be passed as well. They can be sent in an array as shown in Figures 4 and 5 below.

 

 

IMPORTANT! The "timestamp" and "deviceId" pair create a unique key. Each tag can only be sent once with this unique key. Multiple payloads may use the unique key but not duplicate tags.

 

 

The payload shape that is expected can be seen in the following:

 

NOTE: If no timezone info is included e.g. (missing the "Z" or "+00" ISO8601 qualifiers) it will be assumed to be UTC.

 

 

Examples:

[       { "deviceId": "1234-546-98", "timestamp": "2020-11-23T23:43:36Z", "tag1": 01, "tag2": 02, "tag3": 03       } ]

Fig. 2 Payload example 1

 

[ {      "lmdc051wor_val0": 29772,      "lmdc052wor_val0": 29590,      "lmdc053wor_val0": 760,      "timestamp": "2021-11-01-01T12:10:15+00",      "deviceId": "Plant1" } ]

Fig. 3 Payload example 2
 

[ { "tmtag": "799733.01", "pivalue": 5.771, "deviceId": "1",       "timestamp": "2022-10-01T12:09:00+00:00" }, { "tmtag": "437963891.01", "pivalue": 8260, "deviceId": "1",       "timestamp": "2022-10-01T12:08:00+00:00" } ]

Fig. 4 Payload example 3

 

[ {     "80bfb2-dcwf936af481": 27.42,     "deviceId": "82323a3-4fd2-4fff40164fd26b81",     "timestamp": "2021-09-01T15:57:59Z" }, {     "71ef64-xyz870dd3b2e0": 87.73,     "deviceId": "207823a-b52e-40164f40164fd4f",     "timestamp": "2021-09-01T15:57:59Z" } ]

Fig. 5 Payload example4

 

{   "D208": 77318.49,   "H212": -0.927,   "deviceId": "2391-6008-57",   "timestamp": "2021-08-026 15:46:05"       }

Fig. 6 Payload example5

 

Response Codes

After sending a payload, the broker will return a status code. Use these codes when troubleshooting connection or payload issues. Once a connection is successfully established (code 200 or 202) a Pani staff member will finalize the integration and confirm that data ingress is complete.

 

 

Sample Code
The following code presents an example script written in Python that could be used to push data via REST API integration.

 

 

 

A download link to the (Rest_API-Integration.pdf) which details these procedures as found above is provided below:

 

---

Attached PDF documents