---
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
                    - cast
                    - decimate
                    - dp
                    - drop
                    - dump
                    - ebm
                    - fix
                    - gate
                    - jitter_calc
                    - limit_rate
                    - average
                    - restart
                    - scale
                    - shift_seq
                    - shift_ts
                    - skip_first
                    - stats
                    - ts
                    - pps_ts
                    - print
                    node-types:
                    - loopback_internal
                    - influxdb
                    - stats
                    - signal
                    - loopback
                    - test_rtt
                    - socket
                    - file
                    - exec
                    - shmem
                    - zeromq
                    - ngsi
                    - websocket
                    - amqp
                    - mqtt
                    - can
                    - example
                    - ethercat
                    apis:
                    - status
                    - capabilities
                    - config
                    - shutdown
                    - restart
                    - nodes
                    - node
                    - node/start
                    - node/stop
                    - node/pause
                    - node/resume
                    - node/restart
                    - node/stats
                    - node/stats/reset
                    - node/file
                    - paths
                    - path
                    - path/start
                    - path/stop
                    formats:
                    - json
                    - iotagent_ul
                    - json.reserve
                    - villas.binary
                    - villas.web
                    - villas.human
                    - tsv
                    - csv
                    - raw.8
                    - raw.16.be
                    - raw.32.be
                    - raw.64.be
                    - raw.16.le
                    - raw.32.le
                    - raw.64.le
                    - gtnet
                    - gtnet.fake
                    - value
                    
  "/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