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:

Read Service Status

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

API Endpoint

• /api/v2/

Methods

• GET

Request Headers

Responses

Example

Return the HTTP-RPC service status:

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

Read Beats

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

API Endpoint

• /api/v2/beats

• /api/v2/beats?header=<0|1>

Methods

• GET

Request Parameters

Request Headers

Responses

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/v2/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.

API Endpoint

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

Methods

• GET

Request Parameters

Request Headers

Responses

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/v2/logs?node_id=dummy-node&from=2023&to=2024"

Read Nodes

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

API Endpoint

• /api/v2/nodes

• /api/v2/nodes?header=<0|1>

Methods

• GET

Request Parameters

Request Headers

Responses

Example

Return all nodes in database as JSON array:

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

Read Observations

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

API Endpoint

• /api/v2/observs?<parameters>

Methods

• GET

Request Parameters

Request Headers

Responses

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/v2/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.

API Endpoint

• /api/v2/sensors

• /api/v2/sensors?header=<0|1>

Methods

• GET

Request Parameters

Request Headers

Responses

Example

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

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

Read Targets

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

API Endpoint

• /api/v2/targets

• /api/v2/targets?header=<0|1>

Methods

• GET

Request Parameters

Request Headers

Responses

Example

Return all targets in CSV format:

$ curl -s -u <username>:<password> --header "Accept: text/comma-separated-values" \
  "http://localhost/api/v2/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.

API Endpoint

• /api/v2/timeseries?<parameters>

Methods

• GET

Request Parameters

Request Headers

Responses

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/v2/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, JSON Lines, 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).

API Endpoint

• /api/v2/beat

• /api/v2/beat?node_id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

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

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

Read or Create Log

On GET, returns single log of passed id in CSV, JSON, JSON Lines, 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).

API Endpoint

• /api/v2/log

• /api/v2/log?id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

Return a specific log in JSON format:

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

Read or Create Node

On GET, returns node of given id in CSV, JSON, JSON Lines, 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).

API Endpoint

• /api/v2/node

• /api/v2/node?id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

Return node dummy-node in JSON format:

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

Read or Create Observation

On GET, returns observation of given id from database, in CSV, JSON, JSON Lines, 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).

API Endpoint

• /api/v2/observ

• /api/v2/observ?id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

Return a specific observation in JSON format:

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

Read or Create Sensor

On GET, returns sensor of given id in CSV, JSON, JSON Lines, 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).

API Endpoint

• /api/v2/sensor

• /api/v2/sensor?id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

Return sensor dummy-sensor in JSON format:

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

Read or Create Target

On GET, returns target of given id in CSV, JSON, JSON Lines, 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.

API Endpoint

• /api/v2/target

• /api/v2/target?id=<id>

Methods

• GET

• POST

Request Parameters

Request Headers

Responses

Example

Return target dummy-target in JSON format:

$ curl -s -u <username>:<password> --header "Accept: application/json" \
  "http://localhost/api/v2/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 deflate 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.

API Endpoint

• /api/v2/image

Methods

• POST

• PUT

Request Headers

Response Headers

Responses