openapi: '3.0.2'
info:
  title: Tremor Api
  description: 'REST API for tremor'
  version: '1.0'
  
servers:
  - url: http://localhost:9898/
    description: The default ( development ) endpoint on a local ( development ) host

paths:
  ##
  # OnRamp
  ##
  /onramp:
    get:
      summary: Lists onramps
      description: |
        Returns a list of identifiers for each onramp stored in the repository

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      operationId: find_onramps
      tags: [ repo, onramp ]
      responses:
        '200':
          description: 'Find repository managed tremor artefacts'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry_set'
            application/yaml:
              schema:
                $ref: '#/components/schemas/registry_set'
    post:
      summary: Publish a new onramp to the tremor artefact repository
      description: |
        Publishes a new onramp to the tremor artefact repository if the artefact id
        is unique.

        Returns artefact data, on success.

        If an onramp of the same name already exists, a conflict error is returned.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).

      operationId: publish_onramp
      tags: [ repo, onramp ]
      responses:
        '201':
          description: 'Successfully published onramp to tremor registry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/onramp'
            application/yaml:
              schema:
                $ref: '#/components/schemas/onramp'
        '409':
          description: 'An onramp with the same id already exists error'
  /onramp/{artefact-id}:
    get:
      summary: Finds onramp data from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, onramp ]
      operationId: get_onramp_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the onramp
          schema:
            type: string
      responses:
        '200':
          description: 'Get a tremor onramp and any registered instances'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/onramp_state'
            application/yaml:
              schema:
                $ref: '#/components/schemas/onramp_state'
        '404':
          description: 'The onramp was not found and does not exist'
    delete:
      summary: Remove an onramp from tremor artefact repository
      description: |

        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns old artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, onramp ]
      operationId: delete_onramp_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the onramp
          schema:
            type: string
      responses:
        '200':
          description: 'Deleted a onramp'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/onramp'
            application/yaml:
              schema:
                $ref: '#/components/schemas/onramp'
        '409':
          description: 'The onramp has active instances'
        '404':
          description: 'The onramp was not found and does not exist'
  ##
  # OffRamp
  ##
  /offramp:
    get:
      summary: Lists oframps
      description: |
        Returns a list of identifiers for each offramp stored in the repository

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      operationId: find_offramps
      tags: [ repo, offramp ]
      responses:
        '200':
          description: 'Find repository managed tremor offramps'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry_set'
            application/yaml:
              schema:
                $ref: '#/components/schemas/registry_set'
    post:
      summary: Publish a new offramp to the tremor artefact repository
      description: |
        Publishes a new offramp to the tremor artefact repository if the artefact id
        is unique.

        Returns artefact data, on success.

        If an arterfact of the same name already exists, a conflict error is returned.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).

      operationId: publish_offramp
      tags: [ repo, offramp ]
      responses:
        '201':
          description: 'Successfully published offramp to tremor registry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/offramp'
            application/yaml:
              schema:
                $ref: '#/components/schemas/offramp'
        '409':
          description: 'An offramp with the same id already exists error'
  /offramp/{artefact-id}:
    get:
      summary: Get offramp data from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, offramp ]
      operationId: get_offramp_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the offramp
          schema:
            type: string
      responses:
        '200':
          description: 'Get a tremor artefact and any registered instances'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/offramp_state'
            application/yaml:
              schema:
                $ref: '#/components/schemas/offramp_state'
        '404':
          description: 'The offramp was not found and does not exist'
    delete:
      summary: Remove artefact from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns old artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, offramp ]
      operationId: delete_offramp_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the offramp
          schema:
            type: string
      responses:
        '200':
          description: 'Deleted an offramp'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/offramp'
            application/yaml:
              schema:
                $ref: '#/components/schemas/offramp'
        '409':
          description: 'The offramp has active instances'
        '404':
          description: 'The artefact was not found and does not exist'
  ##
  # Pipeline
  ##
  /pipeline:
    get:
      summary: Lists pipelines
      description: |
        Returns a list of identifiers for each pipeline stored in the repository

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      operationId: find_pipelines
      tags: [ repo, pipeline ]
      responses:
        '200':
          description: 'Find repository managed tremor pipelines'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry_set'
            application/yaml:
              schema:
                $ref: '#/components/schemas/registry_set'
    post:
      summary: Publish a new pipeline to the tremor artefact repository
      description: |
        Publishes a new pipeline to the tremor artefact repository if the artefact id
        is unique.

        Returns artefact data, on success.

        If an pipeline of the same name already exists, a conflict error is returned.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).

      operationId: publish_pipeline
      tags: [ repo, pipeline ]
      responses:
        '201':
          description: 'Successfully published pipeline to tremor registry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline'
            application/yaml:
              schema:
                $ref: '#/components/schemas/pipeline'
        '409':
          description: 'A pipeline with the same id already exists error'
  /pipeline/{artefact-id}:
    get:
      summary: Get pipeline data from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, pipeline ]
      operationId: get_pipeline_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the pipeline
          schema:
            type: string
      responses:
        '200':
          description: 'Get a tremor pipeline and any registered instances'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline_state'
            application/yaml:
              schema:
                $ref: '#/components/schemas/pipeline_state'
        '404':
          description: 'The artefact was not found and does not exist'
    delete:
      summary: Remove pipeline from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns old artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, pipeline ]
      operationId: delete_pipeline_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the pipeline
          schema:
            type: string
      responses:
        '200':
          description: 'Deleted pipeline artefact'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline'
            application/yaml:
              schema:
                $ref: '#/components/schemas/pipeline'
        '409':
          description: 'The pipeline has active instances'
        '404':
          description: 'The pipeline was not found and does not exist'
  ##
  # Binding
  ##
  /binding:
    get:
      summary: Lists bindings
      description: |
        Returns a list of identifiers for each binding stored in the repository

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      operationId: find_bindings
      tags: [ repo, binding ]
      responses:
        '200':
          description: 'Find repository managed tremor bindings'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/registry_set'
            application/yaml:
              schema:
                $ref: '#/components/schemas/registry_set'
    post:
      summary: Publish a new binding to the tremor artefact repository
      description: |
        Publishes a new binding to the tremor artefact repository if the artefact id
        is unique.

        Returns artefact data, on success.

        If an arterfact of the same name already exists, a conflict error is returned.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      operationId: publish_binding
      tags: [ repo, binding ]
      responses:
        '201':
          description: 'Successfully published artefact to tremor registry'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binding'
            application/yaml:
              schema:
                $ref: '#/components/schemas/binding'
        '409':
          description: 'An arterfact with the same id already exists error'
  /binding/{artefact-id}:
    get:
      summary: Get binding data from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, binding ]
      operationId: get_binding_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the binding
          schema:
            type: string
      responses:
        '200':
          description: 'Get a binding and any registered instances'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binding_state'
            application/yaml:
              schema:
                $ref: '#/components/schemas/binding_state'
        '404':
          description: 'The artefact was not found and does not exist'
    delete:
      summary: Remove binding from tremor artefact repository
      description: |
        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Returns old artefact data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, binding ]
      operationId: delete_binding_by_id
      parameters:
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the binding
          schema:
            type: string
      responses:
        '200':
          description: 'Deleted binding'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binding'
            application/yaml:
              schema:
                $ref: '#/components/schemas/binding'
        '404':
          description: 'The artefact was not found and does not exist'


  /{artefact-kind}/{artefact-id}/{instance-id}:
    get:
      summary: Get deployed artefact servant data from tremor artefact registry
      description: |
        Given a valid artefact kind parameter of:

        * pipeline
        * onramp
        * offramp
        * binding

        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Given a valid instance identifier for a deployed and running instance of the artefact deployed
        and accesible via the tremor instance registry

        Returns instance data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, reg ]
      operationId: get_artefact_instance_by_id
      parameters:
        - name: artefact-kind
          in: path
          required: true
          description: The type of artefact
          schema:
            type: string
            enum: [ "pipeline", "onramp", "offramp", "binding" ]
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the artefact
          schema:
            type: string
        - name: instance-id
          in: path
          required: true
          description: The ( server ) unique instance id of the artefact
          schema:
            type: string
      responses:
        '200':
          description: 'Get tremor artefact instance data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/artefact'
            application/yaml:
              schema:
                $ref: '#/components/schemas/artefact'
        '404':
          description: 'The artefact instance was not found and does not exist'
    post:
      summary: Publish, deploy and activate instances
      description: |
        Given a valid artefact kind parameter of:

        * pipeline
        * onramp
        * offramp
        * binding

        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Given a valid instance identifier for a deployed and running instance of the artefact deployed
        and accesible via the tremor instance registry

        Creates new instances of artefacts ( if required ), publishes instances
        to the tremor instance registry. If instances are onramps, offramps or
        pipelines new registry values will be created. In the case of onramps
        and offramps these are deployed *after* any dependant pipeline instances
        and then they are interaconnected.

        Returns instance data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, reg ]
      operationId: activate
      parameters:
        - name: artefact-kind
          in: path
          required: true
          description: The type of artefact
          schema:
            type: string
            enum: [ "pipeline", "onramp", "offramp", "binding" ]
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the artefact
          schema:
            type: string
        - name: instance-id
          in: path
          required: true
          description: The ( server ) unique instance id of the artefact
          schema:
            type: string
      responses:
        '201':
          description: 'Old tremor artefact instance data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/artefact'
            application/yaml:
              schema:
                $ref: '#/components/schemas/artefact'
        '404':
          description: 'The artefact instance was not found and does not exist'
    delete:
      summary: Deactivate and unpublish deployed instances
      description: |
        Given a valid artefact kind parameter of:

        * pipeline
        * onramp
        * offramp
        * binding

        Given a valid artefact identifier of an artefact stored in the tremor artefact repository

        Given a valid instance identifier for a deployed and running instance of the artefact deployed
        and accesible via the tremor instance registry

        Deactivates, stops and unpublishes the target instances and any
        dependant instances that are no longer referenced by the runtime.

        Returns old instance data, on success.

        Response data may be either JSON or YAML formatted ( defaults to JSON ).
      tags: [ repo, reg ]
      operationId: deactivate
      parameters:
        - name: artefact-kind
          in: path
          required: true
          description: The type of artefact
          schema:
            type: string
            enum: [ "pipeline", "onramp", "offramp", "binding" ]
        - name: artefact-id
          in: path
          required: true
          description: The ( server ) unique id of the artefact
          schema:
            type: string
        - name: instance-id
          in: path
          required: true
          description: The ( server ) unique instance id of the artefact
          schema:
            type: string
      responses:
        '200':
          description: 'Old tremor artefact instance data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/artefact'
            application/yaml:
              schema:
                $ref: '#/components/schemas/artefact'
        '404':
          description: 'The artefact instance was not found and does not exist'

  /version:
    get:
      summary: Get's the current version
      description: |

        This endpoint returns version information for the current
        version of tremor. Versioning policy follows [Semantic Versioning](https://semver.org/)

      tags: [ version ]
      operationId: get_version
      responses:
        '200':
          description: The current version of treor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/version'
            

components:
  schemas:
    version:
      description: Version information
      properties:
        version:
          type: string
          description: The semantic version code
      required: [ version ]
    
    registry_set:
      description: A list of registry artefacts
      type: array
      items:
        $ref: '#/components/schemas/artefact_id'

    instance_set:
      description: A list of artefact instances 
      type: array
      items:
        $ref: '#/components/schemas/instance_id'

    artefact_id:
      type: string
      pattern: '^[a-z][a-zA-Z_:]*$'

    instance_id:
      $ref: '#/components/schemas/artefact_id'
        
    port_id:
      $ref: '#/components/schemas/artefact_id'

    artefact:
      oneOf:
        - $ref: '#/components/schemas/pipeline'
        - $ref: '#/components/schemas/onramp'
        - $ref: '#/components/schemas/offramp'
        - $ref: '#/components/schemas/binding'
    
    instance:
      oneOf:
        - $ref: '#/components/schemas/mapping'
        
    publish_ok:
      description: Response when a registry publish was succesful
      properties:
        id:
          $ref: '#/components/schemas/artefact_id'
          description: The id of the pubished artefact
      required: [ id ]
      
    pipeline_state:
      description: State of an pipeline, including specification and instances
      type: object
      additionalProperties: false
      properties:
        artefact:
          $ref: '#/components/schemas/pipeline'
        instances:
          $ref: '#/components/schemas/instance_set'

    pipeline:
      description: A tremor pipeline specification
      type: object
      additionalProperties: false
      properties:
        id:
          # description: A unique identifier for this pipeline specification
          $ref: '#/components/schemas/artefact_id'
        description:
          # description: Documentation for this type
          type: string
        interface:
          $ref: "#/components/schemas/interface"
        nodes:
          $ref: "#/components/schemas/nodes"
        links:
          $ref: "#/components/schemas/links"
        metrics_interval_s:
          minimum: 1
          type: integer
      required: [ id, interface, nodes, links ]

    interface:
      type: object
      additionalProperties: false
      properties:
        inputs:
          $ref: "#/components/schemas/stream_names"
        outputs:
          $ref: "#/components/schemas/stream_names"

    stream_names:
      description: The set of input or output stream names
      type: array
      additionalItems: false
      items: 
        $ref: "#/components/schemas/port_id"


    nodes:
      description: The set of operator nodes this pipeline DAG is formed from
      type: array
      additionalItems: false
      items:
        $ref: "#/components/schemas/operator"

    operator:
      description: An operator node in a pipeline or vertex in the pipeline DAG
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/artefact_id'
          description: A pipeline unique identifier for this operator
        description:
          type: string
          description: Documentation for this type
        type:
          type: string
          description: Rust native type for this operator specification
        config:
          type: object
          description: A map of key/value pairs used to configure this operator
      required: [ id, type ]

    links:
      description: The set of connections between nodes/vertices/operators in a pipeline DAG
      type: object
      additionalProperties: false
      # Note: swagger claims this is invalid but it's part of jsonspec
      # we can ignore swaggers complaint here
      patternProperties: 
        '^[a-zA-Z][A-Za-z0-9_/]*$':
          type: array
          additionalItems: false
          items:
            type: string
            pattern: "^[a-zA-Z][A-Za-z0-9_/]*$"

    onramp_state:
      description: State of an onramp, including specification and instances
      type: object
      additionalProperties: false
      properties:
        artefact:
          $ref: '#/components/schemas/onramp'
        instances:
          $ref: '#/components/schemas/instance_set'

    onramp:
      description: A tremor onramp specification
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: Rust native type for this onramp specification
        id:
          # This description would make it an invlaid schema :/
          # description: A unique identifier for this onramp specification
          $ref: '#/components/schemas/artefact_id'
        description:
          type: string
          description: Documentation for this type
        codec:
          # This description would make it an invlaid schema :/
          # description: The codec supported by this offramp
          $ref: "#/components/schemas/codec"
        preprocessors:
          # Preprocessors to be applied to the data
          type: array
          additionalItems: false
          items:
            $ref: "#/components/schemas/preprocessor"
        config:
          type: object
          description: A map of key/value pairs used to configure this onramp
      required: [ type, id ]    
  

    offramp_state:
      description: State of an offramp, including specification and instances
      type: object
      additionalProperties: false
      properties:
        artefact:
          $ref: '#/components/schemas/offramp'
        instances:
          $ref: '#/components/schemas/instance_set'

    offramp:
      description: A tremor offramp specification
      type: object
      additionalProperties: false
      properties:
        type:
          # This description would make it an invlaid schema :/
          # description: Rust native type for this offramp specification
          type: string
        id:
          # This description would make it an invlaid schema :/
          # description: A unique identifier for this offramp specification
          $ref: '#/components/schemas/artefact_id'
        description:
          type: string
          description: Documentation for this type
        codec:
          $ref: "#/components/schemas/codec"
        config:
          type: object
          description: A map of key/value pairs used to configure this onramp

      required: [ type, id ]  
    
    binding_state:
      description: State of an binding, including specification and instances
      type: object
      additionalProperties: false
      properties:
        artefact:
          $ref: '#/components/schemas/binding'
        instances:
          $ref: '#/components/schemas/instance_set'

    binding:
      description: A tremor binding specification
      type: object
      additionalProperties: false
      properties:
        id:
          # This description would make it an invlaid schema :/
          # description: A unique identifier for this binding specification
          $ref: '#/components/schemas/artefact_id'
        description:
          # This description would make it an invlaid schema :/
          # description: Documentation for this type
          type: string
        links:
          $ref: "#/components/schemas/binding_map"
      required: [ id, links ]  
    
    binding_map:
      description: A map of binding specification links
      type: object
      additionalProperties: false
      # Note: swagger claims this is invalid but it's part of jsonspec
      # we can ignore swaggers complaint here
      patternProperties: 
        '^(tremor://)?/(onramp|pipeline)/[a-zA-Z][A-Za-z0-9_]*/[a-zA-Z][A-Za-z0-9_]*$':
          type: array
          additionalItems: false
          items:
            $ref: "#/components/schemas/binding_dst"

    binding_dst:
      type: string
      pattern: '^(tremor://)?/(pipeline|offramp)/[a-zA-Z][A-Za-z0-9_]*/[a-zA-Z][A-Za-z0-9_]*$'

    mapping:
      description: A tremor mapping specification
      type: object

    codec:
      description: The data format supported for encoding/decoding to/from tremor types
      type: string
      enum:
        - json
        - msgpack
        - string
        - 'null'
        - influx

    preprocessor:
      description: Supported preprocessors
      type: string
      enum:
        - lines
        - base64
        - decompress
        - gelf-chunking