RESTful API version 1

This HTTP-based API is arguably the most easily usable among available APIs. It's designed according to RESTful design principle.

Usually it's accessible at http://server/opendaf/ or https://server/opendaf/.

Resource and method summary

Resource	GET	PUT	POST	DELETE
`/measurements/`	get array of VTQ+
`/measurements/:name`	get VTQ and more	start simulation		stop simulation
`/commands/`	get array of VT+
`/commands/:name`	get VT and more	write value
`/alarms/`	get array of alms
`/alarms/:name`	get alarm
`/alarms/:name/activate`			activate alarm
`/alarms/:name/deactivate`			deactivate alarm
`/alarms/:name/acknowledge`			acknowledge alarm
`/archive/measurements/:name/:t_since/:t_until`	read meas.archive
`/archive/commands/:name/:t_since/:t_until`	read cmd. archive
`/archive/alarms/:name/active/:t_since/:t_until`	read alm. archive

Resource details

This chapter covers details of individual resources and methods.

Path parameters

Name	Data type	Description
:name	identifier	resource name
:t_since	number	time interval start as number of seconds since unix epoch
:t_until	number	time interval end as number of seconds since unix epoch

Query parameters

When parameters are referenced in subsequent chapters, required ones are marked with asterisk(*).

Name	Data type	Description
names	comma-separated list of identifiers	Limit operation to names listed
fields	comma-separated list of strings	Limit result JSON to fields listed
value	prefixed-value	Supply value to operation
timestamp	number	Timestamp as floating-point seconds since unix epoch
quality	number	Quality flags according to OPC-DA 2.05 standard
valid-for	number	Operation validity in seconds
resample	number	Resample to given sampling rate in seconds
format	string	Possible values: `json`, `csv`, `bin-v1`
warp_head	boolean	Generate synthetic sample at :t_since
q_at_least	string	Possible values: `good`, `uncertain`, `bad`

Measurements

GET /measurements/

Get properties of measurements. Result schema is measurements.json.

query parameters: names, fields
available fields: name, vtq, address, datatype, raw-datatype, eu-range, raw-range, description

Measurement

GET /measurements/:name

Get properties of the measurement. Result schema is measurement.json.

PUT /measurements/:name

Start simulation on the measurement.

query parameters: value(*), timestamp, quality, valid-for

DELETE /measurements/:name

Stop simulation on the measurement.

POST /measurements/:name

Overwrite measurement value, timestamp, quality.

query parameters: value(*), timestamp, quality

Commands

GET /commands/

Get properties of commands. Result schema is commands.json.

query parameters: names, fields
available fields: name, vt, address, datatype, raw-datatype, eu-range, raw-range, description

Command

GET /command/:name

Get properties of the command. Result schema is command.json.

PUT /commands/:name

Write new command value.

query parameters: value(*)

Alarms

GET /alarms/

Get properties of alarms. Result schema is alarms.json.

query parameters: names, fields
available fields: name, severity, t, authority, state, description

Alarm

GET /alarms/:name

Get properties of the alarm. Result schema is alarm.json.

POST /alarms/:name/activate

Activate the alarm.

POST /alarms/:name/deactivate

Deactivate the alarm.

POST /alarms/:name/acknowledge

Measurement archive

GET /archive/measurements/:name/:t_since/:t_until

Get records from archive for measurement :name since :t_since until :t_until.

query parameters: resample, format, warp_head, q_at_least

Result schema is results-measurement.

Command archive

GET /archive/commands/:name/:t_since/:t_until

Get records from archive for command :name since :t_since until :t_until.

query parameters: resample, format, warp_head

Result schema is results-command.

GET /archive/alarms/:name/:t_since/:t_until

Get records from archive for alarm :name since :t_since until :t_until.

query parameters: format

Result schema is results-alarm.

JSON schemas

Download schemas archive here

Top-level document schemas

communication_object.json

This is not true top-level document, but is a base schema for measurement.json and command.json.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "address": {
            "title": "Connector address",
            "type": "string"
        },
        "datatype": {
            "title": "Datatype",
            "$ref": "datatype.json"
        },
        "raw-datatype": {
            "title": "Raw datatype",
            "$ref": "datatype.json"
        },
        "eu-range": {
            "title": "Engineering range",
            "$ref": "range.json"
        },
        "raw-range": {
            "title": "Raw range",
            "$ref": "range.json"
        }
    },
    "required": ["name","address","datatype","raw-datatype","eu-range","raw-range"]
}

measurement.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "allOf": [
        { "$ref": "communication_object.json" },
        {
            "type": "object",
            "properties": {
                "vtq": { "$ref": "vtq.json" }
            },
            "required": [ "vtq" ]
        }
    ]
}

measurements.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title":    "Map of measurement (name -> measurement)",
    "type":     "object",
    "patternProperties": {
        "[_a-zA-Z][_a-zA-Z0-9]": { "$ref": "measurement.json" }
    }
}

command.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "allOf": [
        { "$ref": "communication_object.json" },
        {
            "type": "object",
            "properties": {
                "vt": { "$ref": "vt.json" }
            },
            "required": [ "vt" ]
        }
    ]
}

commands.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title":    "Map of commands (name -> command)",
    "type":     "object",
    "patternProperties": {
        "[_a-zA-Z][_a-zA-Z0-9]": { "$ref": "command.json" }
    }
}

Top-level archive document schemas

results-measurement.json

{
    "title":    "archive query measurement history results",
    "type":     "object",
    "patternProperties": {
        "[_a-zA-Z][_a-zA-Z0-9]": {
            "type": "array",
            "items": {
                "type": "array",
                "items": [
                    {
                        "title": "value with type prefix",
                        "type": "string"
                    },
                    {
                        "title": "timestamp",
                        "type": "array",
                        "items": [
                            {
                                "title": "seconds since the epoch",
                                "type": "integer",
                                "minimum": 0
                            },
                            {
                                "title": "microseconds",
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 999999
                            }
                        ]
                    },
                    {
                        "title": "quality according to OPC DA 2.05",
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 255
                    }
                ],
                "additionalItems": false
            }
        }
    }
}

results-command.json

{
    "title":    "archive query command history results",
    "type":     "object",
    "patternProperties": {
        "[_a-zA-Z][_a-zA-Z0-9]": {
            "type": "array",
            "items": {
                "type": "array",
                "items": [
                    {
                        "title": "value with type prefix, or null",
                        "type": ["string", "null"]
                    },
                    {
                        "title": "timestamp",
                        "type": "array",
                        "items": [
                            {
                                "title": "seconds since the epoch",
                                "type": "integer",
                                "minimum": 0
                            },
                            {
                                "title": "microseconds",
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 999999
                            }
                        ]
                    }
                ],
                "additionalItems": false
            }
        }
    }
}

results-alarm.json

{
    "title":    "archive query alarm history results",
    "type":     "object",
    "patternProperties": {
        "[_a-zA-Z][_a-zA-Z0-9]": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "t": {
                        "title": "timestamp",
                        "type": "array",
                        "items": [
                            {
                                "title": "seconds since the epoch",
                                "type": "integer",
                                "minimum": 0
                            },
                            {
                                "title": "microseconds",
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 999999
                            }
                        ]
                    },
                    "state": { "enum": ["INACT_ACK", "ACT_UNACK", "ACT_ACK", "INACT_UNACK"] },
                    "description": { "type": "string" },
                    "authority": { "type": "string" }
                },
                "additionalProperties": false,
                "required": [ "t", "state", "description", "authority" ]
            }
        }
    }
}

Basic type schemas

datatype.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "enum": [ "b", "q", "i", "l", "f", "d", "s" ]
}

identifier.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "pattern": "^[0-9_a-zA-Z]{1,64}$"
}

prefixed_value.json

String starting with datatype character, followed by formatted value.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "anyOf": [
        { "pattern": "^b[01]$" },
        { "pattern": "^q[0123]$" },
        { "pattern": "^[il][+-]?[0-9]+$" },
        { "pattern": "^[fd][+-]?[0-9]*\\.?[0-9]+$" },
        { "pattern": "^s" }
    ]
}

quality.json

Number representing measurement quality according to OPC-DA 2.05 standard.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Measurement quality according to OPC DA 2.05",
    "type": "integer",
    "minimum": 0,
    "maximum": 65535,
    "description": "good: (quality & 0xC0) == 0xC0, uncertain: (quality & 0xC0) == 0x40, bad: (quality & 0xC0) == 0x00"
}

timestamp.json

2-element array containing number of seconds and microseconds since the unix epoch (1970-01-01 01:00 UTC).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "timestamp",
    "type": "array",
    "items": [
        {
            "title": "seconds since the epoch",
            "type": "integer",
            "minimum": 0
        },
        {
            "title": "microseconds",
            "type": "integer",
            "minimum": 0,
            "maximum": 999999
        }
    ]
}

range.json

2-element array [low, high] holding range of some value.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "anyOf" : [
            { "$ref": "prefixed_value.json" },
            { "type": "null" }
        ]
    },
    "minItems": 2,
    "maxItems": 2
}

vt.json

2-element array [value,timestamp] holding command value and timestamp.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "value-timestamp tuple",
    "type": "array",
    "items": [
        { "$ref": "prefixed_value.json" },
        { "$ref": "timestamp.json" }
    ],
    "additionalItems": false
}

vtq.json

3-element array [value,timestamp,quality] holding measurement value, timestamp and quality.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "value-timestamp-quality tuple",
    "type": "array",
    "items": [
        { "$ref": "prefixed_value.json" },
        { "$ref": "timestamp.json" },
        { "$ref": "quality.json" }
    ],
    "additionalItems": false
}

severity.json

Numeric alarm severity value.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Alarm severity",
    "type": "integer",
    "minimum": 0,
    "description": "Alarm with severity 0 is the most severe. Severity decreased with its value rising."
}