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

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

  • GET

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

  • GET

Request Parameters

GET Parameter Type Description

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

  • GET

Request Parameters

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).

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

  • GET

Request Parameters

GET Parameter Type Description

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

  • GET

Request Parameters

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).

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

  • GET

Request Parameters

GET Parameter Type Description

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

  • GET

Request Parameters

GET Parameter Type Description

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

  • GET

Request Parameters

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).

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

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

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

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

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

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

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.