DMPACK User Guide

RPC API

All database records are returned in CSV format by default, with content type text/comma-separated-values. Status and error messages are returned as key–values pairs, with content type text/plain.

The following HTTP endpoints are provided by the RPC API:

HTTP Method Endpoint Description

HTTP Method	Endpoint	Description
GET	`/api/v1/`	Read service status.
GET	`/api/v1/beats`	Read beats.
GET	`/api/v1/logs`	Read logs.
GET	`/api/v1/nodes`	Read nodes.
GET	`/api/v1/observs`	Read observations.
GET	`/api/v1/sensors`	Read sensors.
GET	`/api/v1/targets`	Read targets.
GET	`/api/v1/timeseries`	Read time series.
GET, POST	`/api/v1/beat`	Read or update beat.
GET, POST	`/api/v1/log`	Read or create log.
GET, POST	`/api/v1/node`	Read or create node.
GET, POST	`/api/v1/observ`	Read or create observation.
GET, POST	`/api/v1/sensor`	Read or create sensor.
GET, POST	`/api/v1/target`	Read or create target
POST, PUT	`/api/v1/image`	Upload image.

GET

/api/v1/

Read service status.

GET

/api/v1/beats

Read beats.

GET

/api/v1/logs

Read logs.

GET

/api/v1/nodes

Read nodes.

GET

/api/v1/observs

Read observations.

GET

/api/v1/sensors

Read sensors.

GET

/api/v1/targets

Read targets.

GET

/api/v1/timeseries

Read time series.

GET, POST

/api/v1/beat

Read or update beat.

GET, POST

/api/v1/log

Read or create log.

GET, POST

/api/v1/node

Read or create node.

GET, POST

/api/v1/observ

Read or create observation.

GET, POST

/api/v1/sensor

Read or create sensor.

GET, POST

/api/v1/target

Read or create target

POST, PUT

/api/v1/image

Upload image.

Read Service Status

Returns service status in API status format as text/plain.

Endpoint

/api/v1/

HTTP Methods

Request Headers

GET
Name	Values
Accept	`text/plain`

Responses

GET
Status	Description
`200`	Default response.
`401`	Unauthorised.
`500`	Server error.

Example

Return the HTTP-RPC service status:

$ curl -s -u <username>:<password> --header "Accept: text/plain" \
  "http://localhost/api/v1/"

Read Beats

Returns all heartbeats in CSV, JSON, or JSON Lines format from database.

Endpoint

/api/v1/beats
/api/v1/beats?header=<0|1>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`header`	integer	Add CSV header (0 or 1).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Beats are returned.
`401`	Unauthorised.
`404`	No beats found.
`500`	Server error.
`503`	Database error.

Example

Return beats of all nodes in JSON format, pretty-print the result with jq(1):

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/beats" | jq

Read Logs

Returns logs of a given node and time range in CSV, JSON, or JSON Lines format from database. Node id and time range are mandatory.

Endpoint

/api/v1/logs?node_id=<id>&from=<timestamp>&to=<timestamp>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`node_id`	string	Node id.
`from`	string	Start of time range (ISO 8601).
`to`	string	End of time range (ISO 8601).
`header`	integer	Add CSV header (0 or 1).

node_id

string

Node id.

from

string

Start of time range (ISO 8601).

to

string

End of time range (ISO 8601).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Logs are returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	No logs found.
`500`	Server error.
`503`	Database error.

Example

Return all logs of node dummy-node and year 2023 in CSV format:

$ curl -s -u <username>:<password> --header "Accept: text/comma-separated-values" \
  "http://localhost/api/v1/logs?node_id=dummy-node&from=2023&to=2024"

Read Nodes

Returns all nodes in CSV, JSON, or JSON Lines format from database.

Endpoint

/api/v1/nodes
/api/v1/nodes?header=<0|1>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`header`	integer	Add CSV header (0 or 1).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Nodes are returned.
`401`	Unauthorised.
`404`	No nodes found.
`500`	Server error.
`503`	Database error.

Example

Return all nodes in database as JSON array:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/nodes"

Read Observations

Returns observations of given node, sensor, target, and time range from database, in CSV, JSON, or JSON Lines format.

Endpoint

/api/v1/observs?<parameters>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`node_id`	string	Node id.
`sensor_id`	string	Sensor id.
`target_id`	string	Target id.
`response`	string	Response name.
`from`	string	Start of time range (ISO 8601).
`to`	string	End of time range (ISO 8601).
`limit`	integer	Max. number of results (optional).
`header`	integer	Add CSV header (0 or 1).

node_id

string

Node id.

sensor_id

string

Sensor id.

target_id

string

Target id.

response

string

Response name.

from

string

Start of time range (ISO 8601).

to

string

End of time range (ISO 8601).

limit

integer

Max. number of results (optional).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Observations are returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	No observations found.
`500`	Server error.
`503`	Database error.

Example

Return all observations related to node dummy-node, sensor dummy-sensor, and target dummy-target of a single month in JSON format, pretty-print the result with jq(1):

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/observs?node_id=dummy-node&sensor_id=dummy-sensor\
&target_id=dummy-target&from=2023-01&to=2024-01" | jq

Read Sensors

Returns all sensors in CSV, JSON, or JSON Lines format from database.

Endpoint

/api/v1/sensors
/api/v1/sensors?header=<0|1>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`header`	integer	Add CSV header (0 or 1).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Sensors are returned.
`401`	Unauthorised.
`404`	No sensors found.
`500`	Server error.
`503`	Database error.

Example

Return all sensors of node dummy-node in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/sensors?node_id=dummy-node"

Read Targets

Returns all targets in CSV, JSON, or JSON Lines format from database.

Endpoint

/api/v1/targets
/api/v1/targets?header=<0|1>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`header`	integer	Add CSV header (0 or 1).

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

Responses

GET
Status	Description
`200`	Targets are returned.
`401`	Unauthorised.
`404`	No targets found.
`500`	Server error.
`503`	Database error.

Example

Return all targets in CSV format:

$ curl -s -u <username>:<password> --header "Accept: text/comma-separated-values" \
  "http://localhost/api/v1/targets"

Read Time Series

Returns time series as observation views or data points (X/Y records) in CSV format from database. In comparison to the observation endpoint, the time series include only a single response, selected by name.

Endpoint

/api/v1/timeseries?<parameters>

HTTP Methods

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`node_id`	string	Node id.
`sensor_id`	string	Sensor id.
`target_id`	string	Target id.
`response`	string	Response name.
`from`	string	Start of time range (ISO 8601).
`to`	string	End of time range (ISO 8601).
`limit`	integer	Max. number of results (optional).
`header`	integer	Add CSV header (0 or 1).
`view`	integer	Return observation views instead of data points (0 or 1).

node_id

string

Node id.

sensor_id

string

Sensor id.

target_id

string

Target id.

response

string

Response name.

from

string

Start of time range (ISO 8601).

to

string

End of time range (ISO 8601).

limit

integer

Max. number of results (optional).

header

integer

Add CSV header (0 or 1).

view

integer

Return observation views instead of data points (0 or 1).

Request Headers

GET
Name	Values
Accept	`text/comma-separated-values`

Responses

GET
Status	Description
`200`	Observations are returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	No observations found.
`500`	Server error.
`503`	Database error.

Example

Return time series of responses dummy related to node dummy-node, sensor dummy-sensor, and target dummy-sensor, from 2023 to 2024, as X/Y data in CSV format:

$ curl -s -u <username>:<password> --header "Accept: text/comma-separated-values" \
  "http://localhost/api/v1/timeseries?node_id=dummy-node&sensor_id=dummy-sensor\
&target_id=dummy-target&response=dummy&from=2023&to=2024"

For additional meta information, add the parameter &view=1.

Read or Update Beat

On GET, returns heartbeat of a given node in CSV, JSON, or Namelist format from database.

On POST, adds or updates heartbeat given in Namelist format. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the beat was accepted.

If HTTP Basic Auth is used, the user name must match the node_id attribute of the beat, otherwise, the request will be rejected as unauthorised (HTTP 401).

Endpoint

/api/v1/beat
/api/v1/beat?node_id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`node_id`	string	Node id.
`header`	integer	Add CSV header (0 or 1).

node_id

string

Node id.

header

integer

Add CSV header (0 or 1).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Beat is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Beat not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Beat was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return the heartbeat of node dummy-node in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/beat?node_id=dummy-node"

Read or Create Log

On GET, returns single log of passed id in CSV, JSON, or Namelist format from database.

On POST, adds log in Namelist format to database. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the log was accepted.

If HTTP Basic Auth is used, the user name must match the node_id attribute of the log, otherwise, the request will be rejected as unauthorised (HTTP 401).

Endpoint

/api/v1/log
/api/v1/log?id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`id`	string	Log id (UUIDv4).

id

string

Log id (UUIDv4).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Log is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Log not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Log was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`409`	Log exists in database.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return a specific log in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/log?id=51adca2f1d4e42a5829fd1a378c8b6f1"

Read or Create Node

On GET, returns node of given id in CSV, JSON, or Namelist format from database.

On POST, adds node in Namelist format to database. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the node was accepted.

If HTTP Basic Auth is used, the user name must match the node_id attribute of the node, otherwise, the request will be rejected as unauthorised (HTTP 401).

Endpoint

/api/v1/node
/api/v1/node?id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`id`	string	Node id.

id

string

Node id.

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Node is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Node not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Node was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`409`	Node exists in database.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return node dummy-node in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/node?node_id=dummy-node"

Read or Create Observation

On GET, returns observation of given id from database, in CSV, JSON, or Namelist format.

On POST, adds observation in Namelist format to database. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the observation was accepted.

If HTTP Basic Auth is used, the user name must match the node_id attribute of the observation, otherwise, the request will be rejected as unauthorised (HTTP 401).

Endpoint

/api/v1/observ
/api/v1/observ?id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`id`	string	Observation id (UUIDv4).

id

string

Observation id (UUIDv4).

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Observation is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Observation not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Observation was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`409`	Observation exists in database.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return a specific observation in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/observ?id=7b98ae11d80b4ee392fe1a74d2c05809"

Read or Create Sensor

On GET, returns sensor of given id in CSV, JSON, or Namelist format from database.

On POST, adds node in Namelist format to database. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the sensor was accepted.

If HTTP Basic Auth is used, the user name must match the node_id attribute of the sensor, otherwise, the request will be rejected as unauthorised (HTTP 401).

Endpoint

/api/v1/sensor
/api/v1/sensor?id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`id`	string	Sensor id.

id

string

Sensor id.

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Sensor is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Sensor not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Sensor was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`409`	Sensor exists in database.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return sensor dummy-sensor in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/sensor?id=dummy-sensor"

Read or Create Target

On GET, returns target of given id in CSV, JSON, or Namelist format from database.

On POST, adds target in Namelist format to database. Optionally, the payload may be deflate or zstd compressed. The API returns HTTP 201 Created if the target was accepted.

Endpoint

/api/v1/target
/api/v1/target?id=<id>

HTTP Methods

GET
POST

Request Parameters

GET Parameter Type Description

GET Parameter	Type	Description
`id`	string	Target id.

id

string

Target id.

Request Headers

GET
Name	Values
Accept	`application/json`, `application/jsonl`, `application/namelist`, `text/comma-separated-values`

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

Responses

GET
Status	Description
`200`	Target is returned.
`400`	Invalid request.
`401`	Unauthorised.
`404`	Target not found.
`500`	Server error.
`503`	Database error.

POST
Status	Description
`201`	Target was accepted.
`400`	Invalid request or payload.
`409`	Target exists in database.
`413`	Payload too large.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

Example

Return target dummy-target in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v1/target?id=dummy-target"

Upload Image

On POST, tries to create new image transfer and returns a transfer token in HTTP response header dmpack-transfer-id. The meta data of the image must be passed in Fortran 95 Namelist format and may be zlib- or zstd-compressed.

On PUT, searches database for transfer token passed in HTTP request header dmpack-transfer-id and stores payload if found. The payload size must match the image size accepted in the POST request.

Endpoint

/api/v1/image

HTTP Methods

POST
PUT

Request Headers

POST
Name	Values
Content-Encoding	`deflate`, `zstd` (optional)
Content-Type	`application/namelist`

PUT
Name	Values
Content-Length	Image size, must match size passed in POST request.
Content-Type	`image/jpeg`, `image/png`
dmpack-transfer-id	Transfer token for image upload (from POST response).

Response Headers

POST
Name	Values
dmpack-transfer-id	Transfer token for image upload (PUT request).

Responses

POST
Status	Description
`202`	Image transfer was accepted.
`400`	Invalid request or payload.
`401`	Unauthorised.
`405`	Method not allowed.
`409`	Image exists in database.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.

PUT
Status	Description
`201`	Image was successfully uploaded.
`400`	Invalid request or payload.
`401`	Unauthorised.
`405`	Method not allowed.
`415`	Invalid payload format.
`500`	Server error.
`503`	Database error.