---
openapi: '3.0.0'
info:
title: VILLASnode
version: 0.10.0
description: 'A HTTP/REST API for controlling VILLASnode remotely without the need to restart the daemon.'
termsOfService: 'https://www.fein-aachen.org/projects/villas-node/'
contact:
name: 'Steffen Vogel'
email: svogel2@eonerc.rwth-aachen.de
url: 'https://fein-aachen.org/contact/'
license:
name: GPL-v3
url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
externalDocs:
url: 'https://villas.fein-aachen.org/doc/node.html'
servers:
- url: "https://villas.k8s.eonerc.rwth-aachen.de/api/v2"
description: "The production API server in our EONERC OpenStack Kubernetes"
tags:
- name: super-node
description: Global super-node related operations.
- name: nodes
description: Node related operations.
- name: paths
description: Path related operations.
components:
parameters:
node-uuid:
name: uuid
description: A globally unique identifier for each node.
in: path
required: true
schema:
type: string
format: uuid
path-uuid:
name: uuid
description: A globally unique identifier for each path.
in: path
required: true
schema:
type: string
format: uuid
node-uuid-name:
name: uuid-or-name
description: Either a UUID or node-name
in: path
required: true
schema:
oneOf:
- type: string
format: uuid
- type: string
pattern: "[a-z0-9_-]{2,32}"
paths:
"/status":
get:
summary: Get the current status of the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
state: running
version: v0.10.0
release: 1.node_uuid_unique_debug.20201015git335440d
build_id: v0.10.0-335440d-debug
build_date: '20201015'
hostname: ernie
uuid: c9d64cc7-c6e1-4dd4-8873-126318e9d42c
time_now: 1602765814.9240997
time_started: 1602765814.3103526
timezone:
name: CEST
offset: -3600
dst: true
kernel:
sysname: Linux
nodename: ernie
release: 5.6.17-rt10
version: "#5 SMP Fri Jul 10 14:02:33 CEST 2020"
machine: x86_64
domainname: "(none)"
system:
cores_configured: 28
cores: 28
procecces: 780
uptime: 1379600
load:
- 1.66259765625
- 1.271484375
- 1.18701171875
ram:
total: 269994606592
free: 262204465152
shared: 44191744
buffer: 130211840
swap:
total: 4294963200
free: 4294963200
highmem:
total: 0
free: 0
"/capabilities":
get:
summary: Get the capabilities of the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
hooks:
- average
- average
- cast
- decimate
- dp
- drop
- dump
- ebm
- fix
- gate
- jitter_calc
- limit_rate
- pps_ts
- print
- restart
- scale
- shift_seq
- shift_ts
- skip_first
- stats
- ts
node-types:
- amqp
- can
- ethercat
- example
- exec
- file
- influxdb
- kafka
- loopback
- loopback_internal
- mqtt
- ngsi
- redis
- shmem
- signal
- socket
- stats
- temper
- test_rtt
- websocket
- zeromq
apis:
- capabilities
- config
- node
- node/file
- node/pause
- node/restart
- node/resume
- node/start
- node/stats
- node/stats/reset
- node/stop
- nodes
- path
- path/start
- path/stop
- paths
- restart
- shutdown
- status
formats:
- csv
- gtnet
- gtnet.fake
- iotagent_ul
- json
- json.kafka
- json.reserve
- raw
- tsv
- value
- villas.binary
- villas.human
- villas.web
"/config":
get:
summary: Get the currently loaded configuration.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
nodes:
udp_node1:
type: socket
layer: udp
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: '127.0.0.1:12001'
web_node1:
type: websocket
vectorize: 2
series:
- label: Random walk
unit: V
- label: Sine
unit: A
- label: Rect
unit: Var
- label: Ramp
unit: °C
paths:
- in:
- udp_node1
out:
- web_node1
hooks:
- type: decimate
ratio: 2
- in:
- web_node1
out:
- udp_node1
"/restart":
post:
summary: Restart the VILLASnode instance.
tags:
- super-node
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
config:
oneOf:
- type: string
example: "http://example.com/path/to/config.json"
description: An optional path or URI to a new configuration file which should be loaded after restarting the node.
- type: object
description: An optional JSON object containing thenew configuration which should be loaded
responses:
'200':
description: Success. The instance has been restarted.
content:
application/json:
examples:
example1:
value:
restarts: 5
config: http://example.com/path/to/config.json
"/shutdown":
post:
summary: Shutdown the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success. The instance has been shut down.
"/nodes":
get:
summary: Get a list of all configure node instances.
tags:
- nodes
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
- name: udp_node1
uuid: b3df1d73-f483-f16c-5936-4ea48295615c
state: running
affinity: -1
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: '127.0.0.1:12001'
type: socket
layer: udp
- name: web_node1
uuid: 19c84350-c83a-8a3b-224b-43fa591c8998
state: running
affinity: -1
in:
vectorize: 2
signals:
- type: float
enabled: true
name: signal0
- type: float
enabled: true
name: signal1
- type: float
enabled: true
name: signal2
- type: float
enabled: true
name: signal3
out:
vectorize: 2
signals:
- type: float
enabled: true
name: signal0
- type: float
enabled: true
name: signal1
- type: float
enabled: true
name: signal2
type: websocket
vectorize: 2
series:
- label: Random walk
unit: V
- label: Sine
unit: A
- label: Rect
unit: Var
- label: Ramp
unit: °C
"/node/{uuid-or-name}":
get:
summary: Get the information of a specific node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
name: udp_node1
uuid: b3df1d73-f483-f16c-5936-4ea48295615c
state: running
affinity: -1
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: '127.0.0.1:12001'
type: socket
layer: udp
'404':
description: Error. There is no node with the given UUID or the node does not collect statistics.
"/node/{uuid-or-name}/stats":
get:
summary: Get the statistics of a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
rtp.jitter:
low: 1.3293196e-316
high: 0
total: 0
rtp.pkts_lost:
low: 1.3285797e-316
high: 1.3290532e-316
total: 0
rtp.loss_fraction:
low: 3.0e-323
high: 1.32907453e-316
total: 0
age:
low: 1.3288619e-316
high: 1.32909588e-316
total: 0
owd:
low: 3.0e-323
high: 3.0e-322
total: 144
higher: 0
lower: 0
highest: 0.099986117
lowest: 0.09990915800000001
mean: 0.09998063221527778
variance: 7.736879555478282e-11
stddev: 8.795953362472019e-06
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
gap_received:
low: 0
high: 1.32743107e-316
total: 144
higher: 0
lower: 0
highest: 0.10000411000000001
lowest: 0.09999650900000001
mean: 0.09999998652777778
variance: 5.701784607620545e-13
stddev: 7.551016228045431e-07
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
gap_sent:
low: 1.58e-321
high: 1.3292848e-316
total: 144
higher: 0
lower: 0
highest: 0.10004273400000001
lowest: 0.09926839700000001
mean: 0.09999436691666665
variance: 3.7637473716438304e-09
stddev: 6.134938770390321e-05
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
reordered:
low: 8.28904606e-315
high: 1.32930615e-316
total: 0
skipped:
low: 1.32879865e-316
high: 1.3293275e-316
total: 0
'404':
description: Error. There is no node with the given UUID or the node does not collect statistics.
"/node/{uuid-or-name}/stats/reset":
post:
summary: Reset the statistics counters for a specific node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The statistics of the node have been reset.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/start":
post:
summary: Start a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The node has been started.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/stop":
post:
summary: Stop a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The node has been stopped.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/pause":
post:
summary: Pause a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The node has been paused.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/resume":
post:
summary: Resume a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The node has been resumed.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/restart":
post:
summary: Retart a node.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The node has been restarted.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/file/rewind":
post:
summary: Rewind the playback file to the beginning.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
responses:
'200':
description: Success. The file has been rewound.
'404':
description: Error. There is no node with the given UUID.
"/node/{uuid-or-name}/file/seek":
post:
summary: Rewind the playback file to the beginning.
tags:
- nodes
parameters:
- $ref: "#/components/parameters/node-uuid-name"
requestBody:
description: Sample position in file
required: true
content:
application/json:
schema:
type: object
required:
- position
properties:
position:
type: integer
example: 123
description: Skip the first nth samples in the file.
responses:
'200':
description: Success. The read-pointer of the file has been changed.
'404':
description: Error. There is no node with the given UUID.
"/paths":
get:
summary: Get a list of all paths.
tags:
- paths
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
- uuid: 251c99af-4b05-9de4-367e-2bb550412e56
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- udp_node1
out:
- web_node1
- uuid: 61b5674b-95fa-b35f-bff8-c877acf21e3b
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- web_node1
out:
- udp_node1
"/path/{uuid}":
post:
summary: Get details of a single path.
tags:
- paths
parameters:
- $ref: "#/components/parameters/path-uuid"
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
uuid: 251c99af-4b05-9de4-367e-2bb550412e56
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- udp_node1
out:
- web_node1
'404':
description: Error. There is no path with the given UUID.
"/path/{uuid}/start":
post:
summary: Start a path.
tags:
- paths
parameters:
- $ref: "#/components/parameters/path-uuid"
responses:
'200':
description: Success. The path has been started.
'404':
description: Error. There is no path with the given UUID.
"/path/{uuid}/stop":
post:
summary: Start a path.
tags:
- paths
parameters:
- $ref: "#/components/parameters/path-uuid"
responses:
'200':
description: Success. The path has been stopped.
'404':
description: Error. There is no path with the given UUID.
"/graph.{format}":
get:
summary: Get a graph representation of the currently loaded configuration.
tags:
- super-node
parameters:
- in: path
name: format
schema:
type: string
description: The image format of the generated graph.
enum:
- ps
- eps
- txt
- svg
- svgz
- gif
- png
- jpg
- jpeg
- bmp
- dot
- fig
- json
- pdf
- in: query
name: layout
schema:
type: string
description: The Graphviz layout engine used for rendering the graph.
enum:
- circo
- dot
- fdp
- neato
- nop
- nop1
- nop2
- osage
- patchwork
- sfdp
- twopi