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/start
                      - node/stop
                      - node/pause
                      - node/resume
                      - node/restart
                      - stats
                      - stats/reset
                      - file
                      - 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
                          - type: float
                            enabled: true
                            name: signal4
                          - type: float
                            enabled: true
                            name: signal5
                          - type: float
                            enabled: true
                            name: signal6
                          - type: float
                            enabled: true
                            name: signal7
                          - type: float
                            enabled: true
                            name: signal8
                          - type: float
                            enabled: true
                            name: signal9
                          - type: float
                            enabled: true
                            name: signal10
                          - type: float
                            enabled: true
                            name: signal11
                          - type: float
                            enabled: true
                            name: signal12
                          - type: float
                            enabled: true
                            name: signal13
                          - type: float
                            enabled: true
                            name: signal14
                      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}/stats":
    get:
      summary: Get the statistics of a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success
          content:
            application/json:
              examples: 
                example1:
                  value:
                    { test: 1 }
        '404':
          description: Error. There is no node with the given UUID or the node does not collect statistics.

  "/node/{uuid}/stats/reset":
    post:
      summary: Reset the statistics counters for a specific node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      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}/start":
    post:
      summary: Start a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The node has been started.
        '404':
          description: Error. There is no node with the given UUID.

  "/node/{uuid}/stop":
    post:
      summary: Stop a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The node has been stopped.
        '404':
          description: Error. There is no node with the given UUID.

  "/node/{uuid}/pause":
    post:
      summary: Pause a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The node has been paused.
        '404':
          description: Error. There is no node with the given UUID.

  "/node/{uuid}/resume":
    post:
      summary: Resume a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The node has been resumed.
        '404':
          description: Error. There is no node with the given UUID.

  "/node/{uuid}/restart":
    post:
      summary: Retart a node.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The node has been restarted.
        '404':
          description: Error. There is no node with the given UUID.

  "/node/{uuid}/file/rewind":
    post:
      summary: Rewind the playback file to the beginning.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      responses:
        '200':
          description: Success. The file has been rewound.
        '404':
          description: Error. There is no node with the given UUID.
    
  "/node/{uuid}/file/seek":
    post:
      summary: Rewind the playback file to the beginning.
      tags:
      - nodes
      parameters: 
      - $ref: "#/components/parameters/node-uuid"
      requestBody:
        description: Sample position in file
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - position
              properties:
                position:
                  type: integer
                  example: 123
      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}/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.