DAFMan RESTful API - version 2

This HTTP-based API provides access to DAFMan's database actions. Usually it's accessible at http://server/dafman/v2/ or https://server/dafman/v2/.

Resource and method summary

Resource details

This chapter covers details of individual resources and methods.

Path parameters

Query parameters

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

Alarms

GET /alarms/names

Get names of all alarms as Array<String>.

GET /alarms/

Get properties of alarms as Array<Object>. Result schema is alarms.json.

• query parameters: names

Alarm

GET /alarms/:name

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

PUT /alarms/:name

Create or update the alarm configuration. Request schema is alarm.json.

DELETE /alarms/:name

Delete the alarm configuration from database.

Commands

GET /commands/names

Get names of all commands as Array<String>.

GET /commands/

Get properties of commands as Array<Object>. Result schema is commands.json.

• query parameters: names

Command

GET /commands/:name

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

PUT /commands/:name

Create or update the command configuration. Request schema is command.json.

DELETE /commands/:name

Delete the command configuration from database.

Database

GET /cfgdb/database

Get dafman sqlite3 database as Content-type: application/x-sqlite3.

POST /cfgdb/database

Replace configuration database. Request file must be a valid .sqlite3 file and headers should be set to Content-type: application/x-sqlite3

POST /cfgdb/txn

Perform operations defined in request body. Request body schema is txn.json

• query parameters: commit, render

Measurements

GET /measurements/names

Get names of all measurements as Array<String>.

GET /measurements/

Get properties of measurements as Array<Object>. Result schema is measurements.json.

• query parameters: names

Measurement

GET /measurements/:name

Get properties of the Measurement as Object. Result schema is measurement.json.

PUT /measurements/:name

Create or update the Measurement configuration. Request schema is measurement.json.

DELETE /measurements/:name

Delete the Measurement configuration from database.

GET /cfgdb/render

Get configuration render status. Result schema is render.json.

POST /cfgdb/render

Render configuration database.

• query parameters: force - Force configuration render - render even when configuration is up to date.

Providers

GET /providers/names

Get names of all providers as Array<String>.

GET /providers/

Get properties of providers as Array<Object>. Result schema is stack_instantiations.json.

• query parameters: names

Provider

GET /providers/:name

Get properties of the Provider as Object. Result schema is stack_instantiation.json.

PUT /providers/:name

Create or update the Provider configuration. Request schema is stack_instantiation.json.

DELETE /providers/:name

Delete the Provider configuration from database.

Connectors

GET /connectors/names

Get names of all connectors as Array<String>.

GET /connectors/

Get properties of connectors as Array<Object>. Result schema is stack_instantiations.json.

• query parameters: names

Connector

GET /connectors/:name

Get properties of the Connector as Object. Result schema is stack_instantiation.json.

PUT /connectors/:name

Create or update the Connector configuration. Request schema is stack_instantiation.json.

DELETE /connectors/:name

Delete the Connector configuration from database.

Function modules

GET /function-modules/names

Get names of all function modules as Array<String>.

GET /function-modules/

Get properties of function modules as Array<Object>. Result schema is function_modules.json.

• query parameters: names

Function module

GET /function-modules/:name

Get properties of the Function module as Object. Result schema is function_modules.json.

PUT /function-modules/:name

Create or update the Function module configuration. Request schema is function_modules.json.

DELETE /function-modules/:name

Delete the Function module configuration from database.

GET /function-modules/:name/executable

Get Function module executable as Content-type: application/octet-stream.

PUT /function-modules/:name/executable

Replace Function module executable. Request headers should be set to Content-type: application/octet-stream

DELETE /function-modules/:name/executable

Delete Function module executable.

GET /function-modules/:name/executable-stat

Get Function module executable stat as Object. Result schema is executable_stat.json.

Stacks

GET /stacks/connector/names GET /stacks/provider/names

Get names of all stacks for Connector or Provider as Array<String>.

GET /stacks/connector/ GET /stacks/provider/

Get properties of stack Connector or Provider as Array<Object>. Result schema is stacks.json.

• query parameters: names

Stack

GET /stacks/connector/:name GET /stacks/provider/:name

Get properties of the Stack as Object. Result schema is stack.json.

JSON schemas

Download schemas archive here

Top-level document schemas

alarm.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Alarm schema",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "description": {
            "title": "Alarm description",
            "type": "string"
        },
        "severity": { "$ref": "severity.json" },
        "archMode": {
            "title": "Archivation mode",
            "type": "string",
            "enum": [ "none", "change" ]
        },
        "ackMode": {
            "title": "Acknowledge mode",
            "type": "string",
            "enum": [ "manual", "auto" ]
        },
        "enabled": {
            "type": "boolean"
        },
        "trgMeasurement": {
            "type": "string",
            "title": "Trigger measurement"
        },
        "trgOperator": {
            "type": "string",
            "title": "Trigger operator",
            "enum": [ "lt", "gt", "le", "ge", "eq", "ne" ]
        },
        "trgRefValue": {
            "type": "string",
            "title": "Reference value"
        },
        "trgHysteresis": {
            "type": "string",
            "title": "Alarm hysteresis"
        },
        "groupName": {
            "type": "string",
            "title": "Alarm group name"
        },
        "properties": { "$ref": "properties.json" }
    },
    "required": [ "name", "severity" ]
}

alarms.json

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

render.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Render schema",
    "type": "object",
    "properties": {
        "up_to_date": {
            "title": "Configuration render up-to-date status",
            "type": "boolean" 
        }
    },
    "required": [ ]
}

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#",
    "title": "Communication object schema",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "address": { "type": "string" },
        "description": { "type": "string" },
        "datatype": {
            "title": "Datatype",
            "$ref": "datatype.json"
        },
        "rawDatatype": {
            "title": "Raw datatype",
            "$ref": "datatype.json"
        },
        "connectorName": { 
            "title": "Name of Connector",
            "type": "string" 
        },
        "rawRangeLo": {
            "title": "Raw range low",
            "type": "string"
        },
        "rawRangeHi": {
            "title": "Raw range high",
            "type": "string"
        },
        "euRangeLo": {
            "title": "Engineering unit range low",
            "type": "string"
        },
        "euRangeHi": {
            "title": "Engineering unit range high",
            "type": "string"
        },
        "providerAddresses": {
            "title": "Provider Addresses",
            "type": "object",
            "patternProperties": {
                ".{1,}": { "type": "string" }
            }
        },
        "archMode": { 
            "title": "Archivation mode",
            "type": "string",
            "enum": [ "none", "change" ]
        },
        "archPeriod": { 
            "title": "Archivation period",
            "type": "integer"
        },
        "archValueDeadband": { 
            "title": "Archivation value deadband",
            "type": "string"
        },
        "archTimeDeadband": { 
            "title": "Archivation time deadband [ms]",
            "type": "integer"
        },
        "leader": { "type": "string" },
        "stackUmask": { 
            "title": "Stack umask (disabled modules / features)",
            "type": "integer"
        },
        "eu": { 
            "title": "Engineering unit",
            "type": "string"
        },
        "enabled": { "type": "boolean" },
        "properties": { "$ref": "properties.json" }
    },
    "required": [ "name", "datatype" ]
}

measurement.json

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

measurements.json

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

command.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Command schema",
    "type": "object",
    "allOf": [
        { "$ref": "communication_object.json" },
        {
            "type": "object",
            "properties": {
                "initialValue": { 
                    "title": "Command initial value",
                    "type": "string"
                 }
            },
            "required": []
        }
    ]
}

commands.json

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

function_module.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Function module schema",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "description": {
            "title": "Function module description",
            "type": "string"
        },
        "executable": {
            "title": "Executable image path",
            "type": "string"
        },
        "debug": { "type": "boolean" },
        "respawn": { "type": "boolean" },
        "enabled": { "type": "boolean" },
        "termToKill": { 
            "title": "Term to kill [ms]",
            "type": "integer"
        },
        "queryTimeout": { 
            "title": "Query Timeout [ms]",
            "type": "integer"
        },
        "runMode": { 
            "title": "Run mode",
            "type": "string"
        },
        "properties": { "$ref": "properties.json" },
        "env": {
            "title": "Environment variables",
            "type": "object",
            "patternProperties": {
                ".{1,}": { "type": "string" }
            }
        }
    },
    "required": [ "name", "termToKill", "queryTimeout" ]
}

function_modules.json

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

stack_instantiation.json

This is mutual schema for Connector and Provider.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Stack Instantiation (Connector / Provider) schema",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "stackName": {
            "title": "Stack name",
            "type": "string"
        },
        "wdtMeasurement": {
            "title": "Watchdog measurement name",
            "type": "string"
        },
        "vars": {
            "title": "Variables",
            "type": "object",
            "patternProperties": {
                ".{1,}": { "type": "string" }
            }
        },
        "properties": { "$ref": "properties.json" }
    },
    "required": [ "name" ]
}

stack_instantiations.json

This is mutual schema for Connectors and Providers

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

stack.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Stack schema",
    "type": "object",
    "properties": {
        "name": {
            "title": "Unique name",
            "$ref": "identifier.json"
        },
        "description": {
            "title": "Stack description",
            "type": "object"
        },
        "defaults": {
            "title": "Stack defaults",
            "type": "object"
        }
    },
    "required": [ "name" ]
}

stacks.json

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

executable_stat.json

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Function module executable stat schema",
    "type": "object",
    "properties": {
        "mode": { "type": "integer" },
        "uid": { "type": "integer" },
        "gid": { "type": "integer" },
        "size": { "type": "integer" },
        "atime": { "type": "integer" },
        "mtime": { "type": "integer" },
        "ctime": { "type": "integer" }
    },
    "required": []
}

txn.json

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": "^[_a-zA-Z0-9]{1,64}$"
}

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."
}

properties.json

Additional objects' properties

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title":    "Map of properties ( Map<String, String> ))",
    "type":     "object",
  "patternProperties": {
    ".{1,}": { "type": "string" }
  }
}