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-new.k8s.eonerc.rwth-aachen.de/api/v2"
    description: "The production API server in our EONERC OpenStack Kubernetes"
  - url: "http://ernie.acs-lab.eonerc.rwth-aachen.de:8080/api/v2"
    description: "VILLASnode lab instance in ACS laboratory"
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
      
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:
                    { test: 1 }

  "/capabilities":
    get:
      summary: Get the capabilities of the VILLASnode instance.
      tags:
      - super-node
      responses:
        '200':
          description: Success
          content:
            application/json:
              examples: 
                example1:
                  value:
                    build: v0.10.0-4b9e8a6-debug
                    hooks:
                      - average
                      - cast
                      - decimate
                      - drop
                      - dump
                      - ebm
                      - fix
                      - gate
                      - jitter_calc
                      - limit_rate
                      - restart
                      - scale
                      - shift_seq
                      - shift_ts
                      - skip_first
                      - stats
                      - ts
                      - pps_ts
                      - print
                    node-types: []
                    apis:
                      - capabilities
                      - config
                      - shutdown
                      - restart
                      - nodes
                      - node
                      - node/start
                      - node/stop
                      - node/pause
                      - node/resume
                      - node/restart
                      - node/file
                      - node/stats
                      - node/stats/reset
                      - path
                      - paths
                      - path/start
                      - path/stop
                    formats: []
                    

  "/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:
                  type: string
                  example: "http://example.com/path/to/config.json"
                  description: An optional path to a new configuration file which should be loaded after restarting the node.
      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.