swagger: '2.0'

info:
  version: "1.1"
  title: LiveView REST API
  description: |
    This is the LiveView/LDM REST API v1.1. The Swagger YAML file used to generate this can be found [at doc.yaml](doc.yaml). All examples in this document, except for curl, are for swagger-generated clients.
    
    ## Terminology and Notes
    ### Query Strings
    For LiveView tables this is [the full LiveQL query](https://docs.tibco.com/pub/sb-lv/latest/doc/html/lv-reference/lvqueryreference.html) (eg: `select * from MyTable`) and for table-provided tables, this is
    the full query of the type of query string that the table provides (ie. JDBC tables to a MySQL database would have the full MySQL query)
    
    *Note*: The full query is still required—including the `select` on LiveView tables—when issuing a query delete.
    
    ### Query types
    The REST API supports all four types of queries:
    
    | Java API Name             | REST API Name                                        |
    | ------------------------- | ---------------------------------------------------- |
    | `SNAPSHOT`                | (default, leave empty)                               |
    | `SNAPSHOT_AND_CONTINUOUS` | `live`                                               |
    | `CONTINUOUS`              | `continuous`                                         |
    | `DELETE`                  | (use `DELETE` HTTP [verb](#api-Basic-issueDelete))   |
    
    ### Tuples
    Tuples are serialized as JSON objects in the REST API (eg: `{"myfield":"myvalue",...}`). Updates use delta-publishing, and only the changed fields and the primary keys are present. Publishing tuples only requires the primary keys when deleting. Timestamps are serialized as the number of miliseconds since the UNIX Epoch. See the Example Schema and Example Tuple for how they are provided.
    
    ### Schemas
    When receiving schemas in the `begin_snapshot` event or the `X-Query-Schema` header, schemas can be decoded using the following rules:
    
    * The keys of the object are the names of the fields
    * The values of the keys are the types of the fields
    * If the type of the field is a basic type, the value is simply the name of the type. These are:
      * `BLOB`
      * `LONG`
      * `BOOL`
      * `DOUBLE`
      * `INT`
      * `STRING`
      * `TIMESTAMP`
    * If the type of the field is a list, the value is an array with one element: the type of the elements
    * If the type of the field is a nested tuple, the value is a schema of the type of the tuple
    * if the type is `FUNCTION` or `CAPTURE`, these are not supported at this time and the value is `null`
    
    ##### Example Schema
    ```javascript
    {
      "field1": "string",
      "listOfStrings": ["string"],
      "listOfListOfDoubles": [["double"]],
      "nestedTuple": {
        "innerField": ["bool"],
        "secondInnerField": "timestamp"
      },
      "arrayOfTuples": [{
        "field2": "int"
      }]
    }
    ```
    ##### Example Tuple
    ```javascript
    {
      "field1": "This uses the schema in Example Schema",
      "listOfStrings": ["first"],
      "listOfListOfDoubles": [[0.1,0,0],[0,0.1,0],[0,0,0.1]],
      "nestedTuple": {
        "innerField": [true, false, false],
        "secondInnerField": -771942660213
      },
      "arrayOfTuples": [{"field2": 3}, {"field2": 12}, {"field2": 60}]
    }
    ```
    
    ### Deleting
    There are two types of deletion: via a query (query delete) and via the publish path (publish delete).
    Publish deleting is part of publishing, and is when you provide the tuple's primary key to delete. Query deleting is when you provide a query to select rows to be deleted.
     
    ### "include-internal"
    This is provided for exposing the internal LiveView system fields, and should be left off in most cases.
    
    ## Tuple Event Data
    Both the snapshot and continuous endpoints use tuple event data to provide information about the stream.
    ### State Diagram
    ![state diagram of tuple events](states.svg "add, update, and remove events are in one node to simplify the diagram, but are seperate events and in no particular order")
    ### Event Contents
    | type             | key           | data                                   |
    | ---------------- | ------------- | -------------------------------------- |
    | `add`            | Key fields    | Complete tuple                         |
    | `remove`         | Key fields    | *not present*                          |
    | `update`         | Key fields    | Delta tuple (only fields that changed) |
    | `begin_snapshot` | *not present* | Schema and key fields                  |
    | `end_snapshot`   | *not present* | *not present*                          |
    | `exception`      | Error code    | Exception details                      |
    | `heartbeat`      | *not present* | *not present*                          |
    
#host: localhost:10080
basePath: /lv/api/v1
schemes:
  - https # http is only recommended when testing locally
  
securityDefinitions:
  basicAuth:
    type: basic


paths:
  /version:
    get:
      tags: [v1.0,v1.1]
      description: |
        Gets the version of the current server
      operationId: getVersion
      summary: "Version info"
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/VersionInfo"
          
  /tables:
    get:
      tags: [v1.0,v1.1]
      summary: "Table List"
      operationId: getTables
      description: |
        Gets a list of all tables on the server
      produces:
        - application/json
      security:
        - basicAuth: []
      parameters:
        -
          name: with-permission # since v1.1
          in: query
          description: (v1.1+) Only return tables with the given allowedPermission
          required: false
          type: string
        -
          name: with-type # since v1.1
          in: query
          description: (v1.1+) Only return tables with the given type
          required: false
          type: string
          default: all
          enum:
            - all
            - user
            - system
      responses:
        200:
          description: Success
          schema:
            title: tableList
            type: array
            items:
              type: string
            example:
              - LVSessionQueries
              - LVTables
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
  
  /tables/{tablename}:
    get:
      tags: [v1.0,v1.1]
      description: Gets the details of a specific table
      operationId: getTable
      produces:
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: include-internal
          in: query
          description: Should internal fields be included
          required: false
          type: boolean
          default: false
      responses:
        200:
          description: Table details
          schema:
            $ref: "#/definitions/TableInfo"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: Invalid table name
  /tables/{tablename}/tuples:
    put:
      tags: [v1.0,v1.1]
      summary: Publish
      operationId: publishToTable
      description: Publish new list of tuples to a table
      produces: ["application/json"]
      consumes: ["application/json"]
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The name of the target table
        -
          in: query
          name: publisher-id
          type: string
          required: false
          description: An ID for this publisher; used to support server-side recovery features, if desired
        -
          in: body
          name: tuples
          description: The tuples to publish
          required: true
          schema:
            $ref: "#/definitions/PublishData"
      responses:
        422:
          description: Not published
          schema:
            $ref: "#/definitions/StatusType"
        200:
          description: Published
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: Invalid table name
    get:
      tags: [v1.0,v1.1]
      summary: Retrieve data
      operationId: issueSnapshotQuery
      description: Issue a snapshot query on the given table, with optional query.
      produces: 
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: query
          in: query
          description: Query string
          required: false
          type: string
        -
          name: include-internal
          in: query
          description: Should internal fields be included
          required: false
          type: boolean
          default: false
      responses:
        200:
          description: JSON data, based on header
          schema:
            $ref: "#/definitions/Data"
          headers:
            X-Query-Schema:
              type: string
              description: Schema of the query result
            X-Query-Components:
              type: string
              description: The parsed query components
              #schema:
              #  $ref: "#/definitions/Components"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: Invalid table name
        422:
          description: Invalid Query/Non-liveview table
          schema:
            $ref: "#/definitions/StatusType"
    head:
      tags: [v1.0,v1.1]
      summary: Describe query
      operationId: tryQuery
      description: Tries to see if the query will parse, and if so, return the schema and parsed query
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: query
          in: query
          description: Query string
          required: false
          type: string
      responses:
        200:
          description: Query description details
          headers:
            X-Query-Schema:
              type: string
              description: Schema of the query result
            X-Query-Keys:
              type: string
              description: Key field or key fields, comma seperated
            X-Query-Components:
              type: string
              description: The parsed query components
              #schema:
              #  $ref: "#/definitions/Components"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        422:
          description: Invalid Query
    delete:
      tags: [v1.0,v1.1]
      summary: Delete rows
      operationId: issueDelete
      description: Delete specified tuples on the given table, with either a query or a list of tuple's key fields
      produces:
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: query
          in: query
          description: Query string. Ignored when specific tuples provided.
          required: false
          type: string
        -
          in: body
          name: tuples
          description: The tuples to delete (AS_PUBLISH; works with recovery)
          required: false
          schema:
            $ref: "#/definitions/PublishData"
        -
          in: query
          name: publisher-id
          type: string
          required: false
          description: An ID for this publisher (if AS_PUBLISH)
      responses:
        200:
          description: Delete success
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: Invalid table name
        422:
          description: Invalid Query
          schema:
            $ref: "#/definitions/StatusType"
            
  /tables/{tablename}/tuples/{querytype}:
    get:
      tags: [v1.0,v1.1]
      summary: Retreive streaming data
      operationId: issueQuery
      description: Server Sent Event (SSE)-formatted stream of continuous data. Closing this will end query. Must use EventClient or other SSE client.
      produces: 
        - text/event-stream
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: query
          in: query
          description: Query string
          required: false
          type: string
        -
          name: querytype
          in: path
          description: Type of query to run
          required: true
          type: string
          enum:
            - live
            - continuous
        -
          name: include-internal
          in: query
          description: Should internal fields be included
          required: false
          type: boolean
          default: false
      responses:
        200:
          description: Continuous SSE stream
          schema:
            $ref: "#/definitions/Data"
          headers:
            X-Query-Schema:
              type: string
              description: Schema of the query result
            X-Query-Keys:
              type: string
              description: Key field or key fields, comma seperated
            X-Query-Components:
              type: string
              description: The parsed query components
              #schema:
              #  $ref: "#/definitions/Components"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: Invalid table name
        422:
          description: Invalid Query
          schema:
            $ref: "#/definitions/StatusType"
    head:
      tags: [v1.0,v1.1]
      summary: Describe query
      operationId: tryNonSnapshotQuery
      description: Tries to see if the query will parse, and if so, return the schema and parsed query
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: tablename
          type: string
          required: true
          description: The table name to query
        -
          name: querytype
          in: path
          description: Type of query to run
          required: true
          type: string
          enum:
            - live
            - continuous
        -
          name: query
          in: query
          description: Query string
          required: false
          type: string
        -
          name: include-internal
          in: query
          description: Should internal fields be included
          required: false
          type: boolean
          default: false
      responses:
        200:
          description: Query description details
          headers:
            X-Query-Schema:
              type: string
              description: Schema of the query result
            X-Query-Keys:
              type: string
              description: Key field or key fields, comma seperated
            X-Query-Components:
              type: string
              description: The parsed query components
              #schema:
              #  $ref: "#/definitions/Components"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
        422:
          description: Invalid Query
  /alerts: 
    get:
      tags: [v1.1]
      summary: List all alerts
      operationId: getAlertRules
      description: Gets all available alert rules from the server
      produces:
        - application/json
      security:
        - basicAuth: []
      responses:
        200:
          description: List of all available alert rules
          schema:
            type: array
            items:
              $ref: "#/definitions/AlertRule"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
    post:
      tags: [v1.1]
      summary: Alert create
      operationId: createAlertRule
      description: Creates the alert.
      produces:
        - application/json
      consumes:
        - application/json
      security:
        - basicAuth: []
      parameters:
        -
          in: body
          name: alert
          description: The alert rule to create
          required: true
          schema:
            $ref: "#/definitions/AlertRule"
      responses:
        200:
          description: Success status (message contains ID if sucessfull)
          schema:
            $ref: "#/definitions/StatusType"
        422:
          description: Validation failed
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
  /alerts/validator:
    post:
      tags: [v1.1]
      summary: Alert validate
      operationId: validateAlertRule
      description: Validate the alert rule.
      produces:
        - application/json
      consumes:
        - application/json
      security:
        - basicAuth: []
      parameters:
        -
          in: body
          name: alert
          description: The alert rule to validate
          required: true
          schema:
            $ref: "#/definitions/AlertRule"
      responses:
        200:
          description: Validation status
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
  /alerts/{alertid}: 
    get:
      tags: [v1.1]
      summary: Get an Alert
      operationId: getAlertRule
      description: Get specified alert rule
      produces:
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: alertid
          type: string
          required: true
          description: The alert rule's id
      responses:
        200:
          description: Alert rule details
          schema:
            $ref: '#/definitions/AlertRule'
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
    patch:
      tags: [v1.1]
      summary: Alert update
      operationId: updateAlertRule
      description: Updates the alert rule. Only changed fields are needed
      produces:
        - application/json
      consumes:
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: alertid
          type: string
          required: true
          description: The alert rule's id
        -
          in: body
          name: alert
          description: The alert rule to update
          required: true
          schema:
            $ref: "#/definitions/AlertRule"
      responses:
        200:
          description: Success status
          schema:
            $ref: "#/definitions/StatusType"
        422:
          description: Validation failed
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
    delete:
      tags: [v1.1]
      summary: Alert delete
      operationId: deleteAlertRule
      description: Deletes the alert rule.
      produces:
        - application/json
      security:
        - basicAuth: []
      parameters:
        - 
          in: path
          name: alertid
          type: string
          required: true
          description: The alert rule's id 
      responses:
        200:
          description: Success status
          schema:
            $ref: "#/definitions/StatusType"
        401:
          $ref: "#/responses/UnauthorizedError"
        403:
          $ref: "#/responses/ForbiddenError"
definitions:
  AlertRule:
    title: AlertRule
    type: object
    discriminator: trigger
    required:
      - name
    properties:
      status:
        type: string
        readOnly: true
      description:
        type: string
      message:
        type: string
      name:
        type: string
      severity:
        type: integer
        format: int32
      quiescence:
        type: integer
        format: int32
      enabled:
        type: boolean
        default: false
      owner:
        type: string
        #readOnly: true # this is not readonly if the liveview.alert.owner.uselogin=false is set or there is not authentication
      created:
        type: integer
        format: int64
        readOnly: true
      lastUpdate:
        type: integer
        format: int64
        readOnly: true
      id:
        type: string
        readOnly: true
      valid:
        type: boolean
        readOnly: true
      actions:
        type: array
        items:
          $ref: '#/definitions/ActionType'
  AlertRuleCron:
    allOf:
      - $ref: '#/definitions/AlertRule'
      - required:
          - trigger
        title: AlertRule.Cron
        properties:
          trigger:
            type: string
  AlertRuleQuery:
    allOf:
      - $ref: '#/definitions/AlertRule'
      - required:
          - trigger
        title: AlertRule.Query
        properties:
          trigger:
            $ref: '#/definitions/QueryTrigger'
  QueryTrigger:
    title: QueryTrigger
    type: object
    required:
      - query
      - table
    properties:
      query:
        type: string
      table:
        type: string
      type:
        type: string
        enum:
          - continuous
          - live
        default: continuous
      includeInternal:
        type: boolean
        default: false
  ActionType:
    title: ActionType
    type: object
    discriminator: type
    required:
      - type
      - enabled
    properties:
      type:
        type: string
        enum:
          - send_email
          - exec_os
          - exec_java
          - publish_alert
          - send_tuple
          - delete_query
          - lv_publish
      description:
        type: string
      enabled:
        type: boolean
  send_email:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - subject
          - body
        title: ActionType.send_email
        properties:
          to:
            type: array
            items:
              type: string
          cc:
            type: array
            items:
              type: string
          bcc:
            type: array
            items:
              type: string
          subject:
            type: string
          body:
            type: string
  exec_os:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - command
        title: ActionType.exec_os
        properties:
          command:
            type: string
  exec_java:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - className
        title: ActionType.exec_java
        properties:
          className:
            type: string
          parameters:
            type: object
            
  publish_alert:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - message
          - key
          - recipient # mandatory?
        title: ActionType.publish_alert
        properties:
          fieldSubs:
            type: object
          message:
            type: string
          key:
            type: string
          recipient:
            type: string
  delete_query:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - table
          # REVIEW: is predicate mandatory?
        title: ActionType.delete_query
        properties:
          table:
            type: string
          predicate:
            type: string
  send_tuple:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - uri
          - stream
        title: ActionType.send_tuple
        properties:
          fieldSubs:
            type: object
          uri:
            type: string
          stream:
            type: string
  lv_publish:
    allOf:
      - $ref: '#/definitions/ActionType'
      - required:
          - uri
          - table
        title: ActionType.lv_publish
        properties:
          fieldSubs:
            type: object
          uri:
            type: string
          table:
            type: string
  Data:
    title: DataRows
    type: array
    items:
      type: object
      title: tupleEventData
      required: ["type"]
      properties:
        type:
          type: string
          enum:
            - add
            - remove
            - update
            - begin_snapshot
            - end_snapshot
            - begin_delete
            - end_delete
            - exception
            - heartbeat
        key:
          type: string
          description: Opaque index/ID
        data:
          type: object
          description: Tuple
    example:
      - type: snapshotBegin
      - type: add
        data:
          myfield: myString
          myid: 1
        key: 1
      - type: snapshotEnd
  SchemaElement:
    title: SchemaField
    type: object
    required: ["type", "name"]
    properties:
      name:
        type: string
        example: Name
      type:
        type:
          #- string
          #- array
          object
        items:
          $ref: "#/definitions/SchemaElement"
        enum:
          - string
          - double
          - float
          - int
          - long
          - blob
          - timestamp
          - list
  TableInfo:
    title: tableInfo
    type: object
    required: ["name","schema","tableGroup","shortDescription","description","tableSpace","capabilities","queryLanguages","status","statusMessage","isSystemTable","createTime","filter","numServers","rejectedServers", "keyFields", "reqClientCapabilities"]
    properties:
      name:
        type: string
      schema:
        type: object
        title: Schema
        example:
          field1: string
          field2: double
          field3: ["string"]
          field4: 
            nestedField1: double
            nestedField2: string
      tableGroup:
        type: string
        title: TableGroup
      shortDescription:
        type: string
      reqClientCapabilities:
        type: array
        items:
          type: string
      description:
        type: string
      tableSpace:
        type: string
      capabilities:
        type: array
        items:
          type: string
      queryLanguages:
        type: array
        items:
          type: string
      keyFields:
        type: array
        items:
          type: string
      indices:
        type: array
        title: allKeys
        items:
          title: fields
          type: array
          items: 
            type: string
      status:
        title: TableStatus
        type: string
      statusMessage:
        type: string
      isSystemTable:
        type: boolean
      createTime:
        type: integer
        format: int64
      filter:
        type: string
      numServers:
        type: integer
        format: int32
      rejectedServers:
        type: integer
        format: int32
      allowedPermissions: # since v1.1
        type: array
        description: Permissions. Only since v1.1
        items:
          type: string
    example:
      name: LVTables
      schema: '(Name string, TableGroup string, ShortDescription string, Description string, TableSpace string, Capabilities string, QueryLanguages string, isEnabled boolean, Indices string, StatusENUM string, StatusMessage string, IsSystemTable boolean, CreateTime timestamp, Filter string, NumServers int, RejectedServers int)'
      queryLangs: [LIVEVIEW]
      capabilities:
        - Snapshot
        - Continuous
        - Alert Rules
      enabled: true
      requiredClientCapabilities: []
      indicies: [CQSInternalID]
  VersionInfo:
    type: object
    required: [version, build]
    properties:
      version:
        type: number
        format: "float"
        example: 1.1
        title: API Version
      build:
        type: string
        title: Server Version
        example: "10.2.1"
  PublishData:
    type: array
    description: tuples as objects. Timestamps are represented as the number of miliseconds since the unix epoch
    items:
      type: object
      title: tuple
    example:
      - myfield: myValue
        field2: 12
      - myfield: stringValue
        field2: 42
        mytimestamp: 1502481128764 # Miliseconds since UNIX Epoch
  StatusType:
    type: object
    required: [success]
    properties:
      success:
        type: boolean
        example: false
      message:
        type: string
        example: "Table is disabled"
    example:
      projection: '*'
      predicate: ''
      timeWindow: null
      orderBy: null
      groupBy: null
      pivotAggExpr: null
      pivotFor: null
      pivotValues: null
      queryString: null
      table: LVSessions
      limit: -1
      queryType: SNAPSHOT
      predicateDelayInMillis: 0
      isAggregate: false
      includeInternal: false
  Components:
    type: object
    description: The parsed query components
    properties:
      projection:
        type: string
      predicate:
        type: string
      timeWindow:
        type: string
      orderBy:
        type: string
      groupBy:
        type: string
      pivotAggExpr:
        type: string
      pivotFor:
        type: string
      pivotValues:
        type: string
      queryString:
        type: string
      table:
        type: string
      limit:
        type: integer
      queryType:
        type: string
      predicateDelayInMillis:
        type: integer
      isAggregate:
        type: boolean
      includeInternal:
        type: boolean
    example:
      projection: '*'
      predicate: ''
      timeWindow: null
      orderBy: null
      groupBy: null
      pivotAggExpr: null
      pivotFor: null
      pivotValues: null
      queryString: null
      table: LVSessions
      limit: -1
      queryType: SNAPSHOT
      predicateDelayInMillis: 0
      isAggregate: false
      includeInternal: false
responses:
  UnauthorizedError:
    description: Missing authentication
    #headers:
    #  WWW_Authenticate:
    #    type: string
  ForbiddenError:
    description: User doesn't have required permissions