A short guide to the Realiteq API

Introduction to using the RealiteQ API

The Realiteq API is HTTP-based. All interaction with the platform is done over HTTP/S. For better security, it is recommended that all requests are performed over HTTPS (encrypted connection).

1. Introduction

1.1 Conventions

• All requests should be made to the domain name for the client's project, e.g. https://myproject.realiteq.net/

• Parameters should be passed as URL parameters.

• Parameters should be URL-encoded.

• The type of API call is passed using the q parameter, e.g.: https://myproject.realiteq.net/?q=open

• The session key is passed using the skey parameter (see below.)

• The Realiteq server responds to all API calls with a JSON response containing at least one field, the result field. An "OK" value signifies a successful API request:

{ "result": "OK" }

• An error response will include an error code in the `result` field, and a message:

{ "result":"InvalidNodeError", "message":"Invalid node (/node1)" }

• Currently the Realiteq platform accepts requests on both HTTP and HTTPS. We will eventually accept API requests only on HTTPS.

2. Sessions

A session is a context object used to perform various API calls. The session is used to identify the user on which behalf the API is called, and the appropriate permissions. It is also used as a context for subscribing to state changes and providing events to reflect those changes.

Sessions are identified by a session key - skey for short, a random string of 32 characters. Sessions are meant to be short-lived and will be discarded by the server if not used for 10 minutes.

2.1 Opening a session

To open a session use the open query.

Parameters:

• q: open

• u: user name (optional)

• p: password (optional)

(The user credentials are optional. If no user credentials are specified, the session will use the default permissions.)

Example request:

https://myproject.realiteq.net/?q=open&u=johndoe&p=xxxxx

Response fields:

• skey: session key

• user: the user name

• user_title: proper name for the user

• user_rules: a list of access rules associated with the specified user.

Example response:

{
    "result": "OK",
    "skey": "89e9f5bd1eb84a0bbd0eaf1bc9d647b4",
    "user": "johndoe",
    "user_title": "John Doe",
    "user_rules": {
        "/": {
            "read": true,
            "write": null,
            "config": null,
            "modify": null,
            "upload": null
        }
    }
}

2.2 Closing a session

To close a session use the `close` query.

Parameters:

• q: close

• skey: session key

Example request:

https://myproject.realiteq.net/?q=close&skey=xxxxxxx

Example response:

{ "result": "OK"}

2.3 Subscribing to events

To receive state change events, a subscription should be made. A subscription is made to a discrete node in the node tree, and provides events only for that specific nodes. Events for any sub-nodes need to be subscribed to separately.

Parameters:

• q: sub

• skey: session key

• nodes: a list of node paths, separated using !

Example request:

https://myproject.realiteq.net/?q=sub&paths=/r1!/r2&skey=xxxxxxx

Subscribing to a single node can alternatively be done by specifying the node path in the URL path, e.g.:

https://myproject.realiteq.net/r1?q=sub&skey=xxxxxxx

Example response:

{ "result": "OK"}

2.4 Unsubscribing

To stop receiving state change events for a specific node, use the unsub query. Parameters:

• q: unsub

• skey: session key

• nodes: a list of node paths, separated using !

Example request:

https://myproject.realiteq.net/?q=unsub&paths=/r1!/r2&skey=xxxxxxx

Unsubscribing from a single node can alternatively be done by specifying the node path in the URL path, e.g.:

https://myproject.realiteq.net/r1?q=unsub&skey=xxxxxxx

Example response:

{"result": "OK"}

2.5 Receiving events

Events can be received by using the events query. Depending on the various request parameters, the server can block the response until a timeout has elapsed or events are available. The server can also stream events as they become available. In addition to the plain JSON response, the server can also provide streaming events using the SSE standard (Server-Sent Events).

Parameters:

• q: events

• skey: session key

• m: query mode: simple, block or stream. The default is simple

• t: timeout in seconds

• k: keep-alive frequency in seconds

Simple mode

When using the simple mode, the server responds *immediately* with any pending events:

https://myproject.realiteq.net/?q=events&skey=xxxxxxx

Example response (see discussion of event fields below):

{
    "result": "OK",
    "events": [
        {
            "id": 3,
            "kind": 101,
            "path": "/d0",
            "quality": 1,
            "stamp": 1497874006.742,
            "value": null,
            "unformatted_value": null,
            "datatype": 1
        }
    ]
}

Blocking mode

When using the block mode, the server will block until an event is generated for the client's session. If no event is available within the specified timeout period, the server responds with an empty list of events:

https://myproject.realiteq.net/?q=events&m=block&t=15&skey=xxxxxxx

Example response:

{
    "result": "OK",
    "events": [
        {
            "id": 3,
            "kind": 101,
            "path": "/d0",
            "quality": 1,
            "stamp": 1497874006.742,
            "value": null,
            "unformatted_value": null,
            "datatype": 1
        }
    ]
}

Receiving events using SSE (Server-Sent Events)

To receive events using SSE, the following parameters should be specified:

• q: events.sse

• skey: session key

• t: timeout in seconds

• k: keep-alive frequency in seconds

An example for setting up a Javascript EventSource:

var url = "https://myproject.realiteq.net/?q=events.sse&t=300&k=15&skey=" + skey;
var eventSource = new EventSource(url);
eventSource.addEventListener('message', function(msg) {
    var e = JSON.parse(msg.data);
    processEvent(e);
}, false);

Event fields

• kind: kind of event:

  • 101: state change

• path: path of node

• quality: quality of node value:

  • 0: unknown value

  • 1: good value

  • 2: bad value

  • 3: invalid value

  • 4: simulated value

  • 5: forced value

• stamp: time stamp in Unix epoch seconds

• value: value of node

• unformatted_value: value of node without formatting

• datatype: data type:

  • 0: text value

  • 1: integer value

  • 2: float value

  • 3: boolean value

3. Nodes

Nodes are objects having distinct states and arranged in a hierarchical tree. A node may be a group (a container of child nodes), a point (representing a process value), or an alarm (representing a process alarm). A node is referenced by a path specifying its location in the node tree, with levels separated using a slash, e.g. /unit1/values/v1.

Each node has its own attributes which affect its behaviour, and a state. A node's state represents an observed value or a calculated value derived from observed values. The state will include a quality field denoting the reliability of the measurement (for example, when no communication to the source of the value, for example a PLC, is possible, the quality will be set to 'bad'), a stamp denoting the time the observation was made, a value, and the value's data type (integer, floating-point number, boolean or text).

Node states can be optionally recorded to history, and can thereafter be queried in order to monitor value changes over time.

3.1 Querying real-time node states

To query the current state of a node, use the state query. The response can be rendered in JSON or XML. The path part of the URL represents the node to query. Querying for multiple nodes at once is possible by using the nodes parameter as described below.

The response will include for each specified node the following attributes:

• quality: an integer signifying a state class:

  • 0: unknown

  • 1: good

  • 2: bad (usually meaning error in acquiring value from PLC)

  • 3: invalid (usually meaning the node is not known by either PLC, iCEX or server)

  • 4: simulated

  • 5: forced

• stamp: a Unix time stamp

• value: the node's value

• unformatted_value: the node's value without formatting

• datatype: an integer signifying the datatype:

  • 0: text

  • 1: integer

  • 2: floating-point number

  • 3: boolean

Parameters:

• q: state

• f: the format to use for the response, one of json, xml (default: json)

• nodes: optional parameter for querying history for multiple nodes. nodes paths are separated using an exclamation mark and are relative to the path given in the URL. For example, v1!v2

• tag: optional parameter for selecting nodes by tagnames. Tagnames are separated using an exclamation mark. Tagnames will be searched among subnodes of the specified path.

Example request:

https://myproject.realiteq.net/?q=state&nodes=v1!v2

Example response:

{
    "result": "OK",
    "nodes": {
        "/v2": {
            "quality": 5,
            "stamp": 1505232681.858238,
            "value": "13",
            "unformatted_value": "13",
            "datatype": 1
        },
        "/v1": {
            "quality": 5,
            "stamp": 1507281846.950989,
            "value": "21",
            "unformatted_value":
            "21",
            "datatype": 1
        }
    }
}

3.2 Querying historical node states

To query node values, use the history query. The response can be rendered in a number of different formats: JSON, XML, CSV or PDF.

The path part of the URL represents the node to query. Querying for multiple nodes at once is possible by using the nodes parameter as described below.

Parameters:

• q: history

• f: the format to use for the response, one of json, csv, xml, pdf (default: json)

• nodes: optional parameter for querying history for multiple nodes. nodes paths are separated using an exclamation mark and are relative to the path given in the URL. For example, v1!v2

• t1, t2: historical time range start and stop in unix epoch integer values-

• period: alternative time range expressed in seconds counting back from the present moment, e.g. 86400 will limit the query to the last 24 hours

The response will contain a list of historical states within the period defined using the t1 and t2 parameters, or alteratively the period parameter.

Example request:

https://myproject.realiteq.net/?q=history&nodes=v1!v2&period=86400

Example response:

{
    "result": "OK",
    "states": [
        {
            "stamp": 1503570069,
            "quality": 5,
            "value": 32,
            "unformatted_value": 32,
            "datatype": 1,
            "path": "/v2"
        },
        {
            "stamp": 1503560763,
            "quality": 5,
            "value": 132,
            "unformatted_value": 132,
            "datatype": 1,
            "path": "/v1"
        },
        {
            "stamp": 1503502127,
            "quality": 5,
            "value": 21,
            "unformatted_value": 21,
            "datatype": 1,
            "path": "/v1"
        },
        {
            "stamp": 1503401639,
            "quality": 5,
            "value": 133,
            "unformatted_value": 133,
            "datatype": 1,
            "path": "/v1"
        }
    ],
    "count": 4
}

Getting history for multiple nodes in tabulated form

Historical values can also be retrieved in a sort of 'pivot table', with a separate column for each node. To retrieve historical values in tabulated mode, add the following parameter:

- table: 1

For example, the following query:

https://myproject.realiteq.net/?q=history&period=3600&nodes=v1!v2&table=1

will get the following response:

{
    "result": "OK",
    "states": [
        {
            "stamp": 1503570069,
            "values": [1, null]
        },
        {
            "stamp": 1503560763,
            "values": [1,null]
        }
    ],
    "count": 2
}

Getting historical values at regular intervals

Historical values can also be retrieved at regular intervals of time, instead of the proper time at which they were observed. In this mode of retrieval, called _interpolated_ mode, the Realiteq platform provides the last known state of the relevant node or nodes at regular intervals.

To retrieve a node's historical states in interpolated mode, add the following parameters:

• interpolate: 1

• interval: the interval in seconds (for example, 3600 for intervals of 1 hour)

When retrieving history for multiple nodes in interpolated mode, the tabulated mode is implied, that is values will always be provided in tabulated form.

Example:

https://myproject.realiteq.net//?q=history&period=120&nodes=v1!v2&table=1&interpolate=1&interval=60

Example response:

{
    "result": "OK",
    "states": [
        {
            "stamp": 1503573600,
            "values": ["132", "32"]
        },
        {
            "stamp": 1503573540,
            "values": ["132", "32"]
        },
        {
            "stamp": 1503573480,
            "values": ["132", "32"]
        },
        {
            "stamp": 1503573420,
            "values": ["132", "32"]
        }
    ],
    "count": 4
}

3.3 Using web hooks to receive state updates

In addition to using sessions and events to receive state updates, nodes can be configured to send updates whenever the node's state is updated. The updates are sent using HTTP/S to a server provided by the client.

To configure remote updates, use the Realiteq web interface. For each node for which remote update is desired, set the remote update field to the URL of your server.

State updates will be sent as HTTP POST requests with the following fields in URL encoding:

• q: remote_update

• path: the node path

• quality: quality of state (0 - unknown, 1 - good, 2 - bad, 3 - invalid, 4 - forced, 5 - simulated)

• stamp: time stamp in string format

• raw_stamp: time stamp in unix epoch

• value: the value

• unformatted_value: the value without formatting

• datatype: the data type (0 - text, 1 - integer, 2 - floating point, 3 - boolean)