swagger: '2.0'

info:
  title: IoT TS Aggregates API
  description: |

    The aggregate service enables querying aggregated time series data including
    * aggregates generated on the fly
    * aggregates pre-calculated during ingest

    Depending on, if asset (entity) is performance or simulation asset (entity), different aggregation intervals are supported.

    ### Performance Asset (Entity)

    Pre-calculated aggregates are available in the following intervals
    * 2 minute
    * 1 hour
    * 1 day

    Intervals smaller than 2 minutes are also available and generated on the fly.


    ### Simulation Asset (Entity)

    Pre-calculated aggregates are available in the following intervals
    * 1 millisecond
    * 10 millisecond
    * 1 second

    On the fly aggregation is not supported for simulation assets (entities).

    Note: There might be time series data ingested in the past for which pre-calculated aggregates have not been computed. In that case for simulation assets (entities), no aggregated data is returned.

  version: "3.6.0"
  x-visibility: "external"

schemes:
  - https

basePath: /api/iottsaggregates/v3

produces:
  - application/json

securityDefinitions:
  aggregates:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      iot.tsa.r: read aggregated time series

paths:

  /aggregates/{entity}/{propertyset}:
    get:
      deprecated: true
      summary: read aggregated time series
      tags:
        - aggregates
      description: |
        Read time series data aggregated over a certain interval for a single asset (entity) and aspect (property set) within the provided time range.
      operationId: retrieveAggregates
      security:
        - aggregates:
            - iot.tsa.r
      parameters:
        - name: entity
          in: path
          description: Unique identifier of the asset (entity).
          required: true
          type: string
          minLength: 32
          maxLength: 32
          pattern: "[a-f0-9]{32}"
        - name: propertyset
          in: path
          description: Name of the aspect (property set).
          required: true
          type: string
        - name: from
          in: query
          description: Beginning of the time range to read.
          required: true
          type: string
          format: date-time
        - name: to
          in: query
          description: End of the time range to read.
          required: true
          type: string
          format: date-time
        - name: intervalValue
          in: query
          description:
            Interval duration for the aggregates in intervalUnits.
          required: true
          type: number
          format: long
        - name: intervalUnit
          in: query
          description:
            Interval duration unit for the aggregates.
          required: true
          type: string
        - name: select
          in: query
          description: Properties and fields to select. By default all properties and the available fields are returned. Providing a property name selects all fields of a property. A property name followed by a '.' and field name selects a specific field of a property.
          required: false
          type: string
      responses:
        '200':
          description: array of aggregated time series
          schema:
            type: array
            items:
              $ref: '#/definitions/aggregates'
        '400':
          description: |
                The request will return 400 BAD REQUEST for the cases below
                - The from time is greater than to time.
                - An invalid interval value or unit is provided.
                
          schema:
            $ref: '#/definitions/badrequest'
        '401':
          description: unauthorized
          schema:
            $ref: '#/definitions/unauthorized'
        '404':
          description: asset (entity) not found
          schema:
            $ref: '#/definitions/notfound'

        '503':
          description: |
                The request will return HTTP 503(Service Unavailable). Probable cases are:
                - Server not available
          schema:
            $ref: '#/definitions/error'

        '403':
          description: User is not having required access to perform this operation on given Asset/Entity {assetId}. Consult tenant admin for appropriate access.
          schema:
            $ref: '#/definitions/forbidden'

        '429':
          description: |
                Too many requests that can be arised based on subsequent case:
                - User has sent too many requests in a given amount of time. 
                
                A Retry-After header might be included to this response indicating how long in 'seconds' to wait before making a new request.
          headers:
            Retry-After:
              type: integer
              description: Time in seconds to wait before making a new request
          schema:
            $ref: '#/definitions/toomanyrequests'

        'default':
          description: unexpected error
          schema:
            $ref: '#/definitions/error'

definitions:

  aggregates:
    type: object
    description: Aggregates for the properties of the aspect (property set)
    required:
      - starttime
      - endtime
    properties:

      starttime:
        type: string
        format: date-time
        description: start time of the interval (exclusive)

      endtime:
        type: string
        format: date-time
        description: end time of the interval (inclusive)

    additionalProperties:
        $ref: '#/definitions/aggregate'
        
    example :
       starttime: "2017-05-01T00:12:00Z"
       endtime: "2017-05-01T00:16:00Z"
       pressure : 
           countgood: 4
           countuncertain: 0
           countbad: 0
           sum: 178
           average: 93.75
           mintime: "2017-05-01T00:10:00Z"
           minvalue: 93
           maxtime: "2017-05-01T00:10:00Z"
           maxvalue: 95
           firsttime: "2017-05-01T00:09:00Z"
           firstvalue: 93
           lasttime: "2017-05-01T00:12:00Z"
           lastvalue: 94
           sd: 14.36

  aggregate:
    type: object
    properties:
      countgood:
        type: integer
        description: Number of good records in the aggregated interval.

      countuncertain:
        type: integer
        description: Number of uncertain records in the aggregated interval.

      countbad:
        type: integer
        description: Number of bad records in the aggregated interval.

      sum:
        type: number
        format: double
        description: Sum of the values within the interval.

      average:
        type: number
        format: double
        description: Average of the values within the interval.

      mintime:
        type: string
        format: date-time
        description: Timestamp of the minimum value within the interval.

      minvalue:
        type: number
        format: double
        description: Minimum value within the interval.

      maxtime:
        type: string
        format: date-time
        description: Timestamp of the maximum value within the interval.

      maxvalue:
        type: number
        format: double
        description: Maximum value within the interval.

      firsttime:
        type: string
        format: date-time
        description: Timestamp of the first value within the interval.

      firstvalue:
        type: number
        format: double
        description: First value within the interval.

      lasttime:
        type: string
        format: date-time
        description: Timestamp of the last measurement within the interval.

      lastvalue:
        type: number
        format: double
        description: Last value within the interval.
        
      sd:
        type: number
        format: double
        description: Standard deviation of the values within the interval. It will return null, if number goes beyond Double range during calculation of Standard Deviation.

  unauthorized:
    type: object
    properties:
      id:
        type: string
        format: uuid
      message:
        type: string
        example: Not authorized to access this resource.

  badrequest:
    type: object
    properties:
      id:
        type: string
        format: uuid
      message:
        type: string
        example: The request is not valid.

  notfound:
    type: object
    properties:
      id:
        type: string
        format: uuid
      message:
        type: string
        example: Resource not found.

  forbidden:
    type: object
    properties:
      id:
        type: string
        format: uuid
      message:
        type: string
        example: User is not having required access to perform this operation on given Asset {assetId}. Consult tenant admin for appropriate access.

  toomanyrequests:
    type: object
    properties:                
      message:
        type: string    
    example:
      message: "API rate limit exceeded"

  error:
    type: object
    properties:
      id:
        type: string
        format: uuid
      message:
        type: string
