swagger: '2.0'
info:
  title: IoT File API
  description: The IoT File API
  version: "4.0.0"
  x-visibility: "external"

schemes:
  - https

basePath: /api/iotfile/v4
tags:
  - name: File Delete Rules (TTL)
    description: File Delete Rules (Time To Live) operations.

securityDefinitions:
  fileservice:
    type: oauth2
    flow: accessCode
    authorizationUrl: https://oauth.simple.api/authorization
    tokenUrl: https://oauth.simple.api/token
    scopes:
      iot.fil.w: write operations on file delete (TTL) rule
      iot.fil.r: get operations on file delete (TTL) rule
      iot.fil.d: delete operations on file delete (TTL) rule

paths:
  /fileDeleteRules:
    post:
      summary: create file delete rules (Time To Live - TTL)
      tags:
        - File Delete Rules (TTL)
      description: |
        1. Delete all the files on the given path for a given asset identifier
        2. Files last updated before the given number of days as per the rule definition will be considered for delete operation.
        3. Maximum 50 file delete (TTL) rules can be created per tenant.
        4. Only one rule per hierarchy of folder path and asset can be created.
        
        * Once file delete (TTL) rules is created, it's executions will run on daily or alternate day basis based on the number of records to delete as per the given request
        * Only one element corresponding to one input asset is currently allowed to be passed in the input array

      operationId: postFileDeleteRules
      security:
        - fileservice:
            - iot.fil.w
      produces:
        - application/json
      parameters:
        - name: fileDeleteRule
          in: body
          description: Request for file delete (TTL) rule
          required: true
          schema:
            $ref: '#/definitions/fileDeleteRuleRequest'
      responses:
        '202':
          description: file delete (TTL) rule request has been accepted
          schema:
            $ref: "#/definitions/fileDeleteRuleCreateResponse"
        '400':
          description: |
            Bad request. Possible errors:
            <br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message (parametrized)</th>
              </tr>
              <tr>
                <td>ruleOnAssetPathExist</td>
                <td>File delete (TTL) rule on the asset and path hierarchy already exists.</td>
              </tr>
              <tr>
                <td>maxTTLRuleLimit</td>
                <td>Maximum {max} number of file delete (TTL) rules can be created.</td>
              </tr>
              <tr>
                <td>pathInvalid</td>
                <td>Provided folder path is invalid</td>
              </tr>
              <tr>
                <td>mandatoryField</td>
                <td>Mandatory field assetId is not given.</td>
              </tr>
              <tr>
                <td>assetInvalid</td>
                <td>Given assetId does not exists or invalid.</td>
              </tr>
              <tr>
                <td>deleteAfterDaysInvalid</td>
                <td>Value for deleteAfterDays should be between 30 to 365.</td>
              </tr>
              <tr>
              <td>requestCountInvalid</td>
              <td>Maximum request allowed at a time are 1</td>
              </tr>
              <tr>
              <td>deleteAfterDaysMinInvalid</td>
              <td>Minimum Value for deleteAfterDays should be 30.</td>
              </tr>
              <tr>
              <td>deleteAfterDaysMaxInvalid</td>
              <td>Maximum Value for deleteAfterDays should be 365.</td>
              </tr>
            </table>
          schema:
            $ref: '#/definitions/Errors'
        '403':
          description: |
            <b>unauthorized</b>: Not Authorized to perform this action
          schema:
            $ref: '#/definitions/unauthorized'
        '429':
          description: |
            <b>TooManyRequests</b>: Too Many Requests
            
            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/RateLimiter'
        '500':
          description: |
            <b>ServerError</b>: Internal server error
          schema:
            $ref: '#/definitions/internalservererror'
        '503':
          description: |
            <b>ServerError</b>: Service unavailable
          schema:
            $ref: '#/definitions/serviceunavailable'
    get:
      summary: get file delete rules (Time To Live - TTL)
      tags:
        - File Delete Rules (TTL)
      description: |
        get file delete rules (Time To Live - TTL)
      operationId: getFileDeleteRules
      security:
        - fileservice:
            - iot.fil.r
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/size'
        - name: filter
          in: query
          description: filter based on assetId field example value filter={"assetId":"4a560a4dfd104a0f897b779bce8f1f09"}, only 1 assetId in filter is possible as of now
          required: false
          type: string
      responses:
        '200':
          description: file delete (TTL) rule get request
          schema:
            $ref: "#/definitions/fileDeleteRulesPageResponse"
        '403':
          description: |
            <b>unauthorized</b>: Not Authorized to perform this action
          schema:
            $ref: '#/definitions/unauthorized'
        '429':
          description: |
            <b>TooManyRequests</b>: Too Many Requests
            
            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/RateLimiter'
        '500':
          description: |
            <b>ServerError</b>: Internal server error
          schema:
            $ref: '#/definitions/internalservererror'
        '503':
          description: |
            <b>ServerError</b>: Service unavailable
          schema:
            $ref: '#/definitions/serviceunavailable'
  /fileDeleteRules/{id}:
    get:
      summary: get file delete rule (Time To Live - TTL) for the given id
      tags:
        - File Delete Rules (TTL)
      description: |
        get file delete rule (Time To Live - TTL) for the given id
      operationId: getFileDeleteRulesById
      security:
        - fileservice:
            - iot.fil.r
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: file delete (TTL) rule id
          required: true
          type: string
          minLength: 12
          maxLength: 36
          pattern: "[a-f0-9]{12-36}"
      responses:
        '200':
          description: file delete (TTL) get rule
          schema:
            $ref: "#/definitions/fileDeleteRuleResponse"
        '403':
          description: |
            <b>unauthorized</b>: Not Authorized to perform this action
          schema:
            $ref: '#/definitions/unauthorized'
        '404':
          description: |
            <b>dataNotFound</b>: File delete (TTL) rule does not exist.
          schema:
            $ref: '#/definitions/Errors'
        '429':
          description: |
            <b>TooManyRequests</b>: Too Many Requests
            
            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/RateLimiter'
        '500':
          description: |
            <b>ServerError</b>: Internal server error
          schema:
            $ref: '#/definitions/internalservererror'
        '503':
          description: |
            <b>ServerError</b>: Service unavailable
          schema:
            $ref: '#/definitions/serviceunavailable'
    delete:
      summary: delete file delete rules (Time To Live - TTL)
      tags:
        - File Delete Rules (TTL)
      description: |
        Delete file delete rule (Time To Live - TTL) for the given id
      operationId: deleteFileDeleteRulesById
      security:
        - fileservice:
            - iot.fil.d
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: file delete (TTL) rule id
          required: true
          type: string
          minLength: 32
          maxLength: 36
          pattern: "[a-f0-9]{12-36}"
      responses:
        '204':
          description: deleted
        '403':
          description: |
            <b>unauthorized</b>: Not Authorized to perform this action
          schema:
            $ref: '#/definitions/unauthorized'
        '404':
          description: |
            <b>dataNotFound</b>: File delete (TTL) rule does not exist.
          schema:
            $ref: '#/definitions/Errors'
        '429':
          description: |
            <b>TooManyRequests</b>: Too Many Requests
            
            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/RateLimiter'
        '500':
          description: |
            <b>ServerError</b>: Internal server error
          schema:
            $ref: '#/definitions/internalservererror'
        '503':
          description: |
            <b>ServerError</b>: Service unavailable
          schema:
            $ref: '#/definitions/serviceunavailable'
definitions:
  unauthorized:
    type: object
    properties:
      id:
        type: string
        format: uuid2
      message:
        type: string
        example: Not authorized to access this resource.
  internalservererror:
    type: object
    properties:
      id:
        type: string
        format: uuid2
      message:
        type: string
        example: Internal server error occured while serving the request.
  serviceunavailable:
    type: object
    properties:
      id:
        type: string
        format: uuid2
      message:
        type: string
        example: Service not available.
  RateLimiter:
    type: object
    properties:
      message:
        type: string
    example:
      message: "API rate limit exceeded"
  Errors:
    type: object
    description: Error response body model.
    properties:
      errors:
        type: array
        description: >-
          Concrete error codes and messages are defined at operation error
          response descriptions in this API specification.
        items:
          type: object
          properties:
            code:
              type: string
              description: Unique error code. Every code is bound to one message.
              format: mdsp.iot.iotfile.<suffix>
              example: mdsp.iot.iotfile.exampleCode
            logref:
              type: string
              description: Logging correlation ID for debugging purposes.
              example: 0bff7e7a-cd25-4576-9908-4180ef086174
            message:
              type: string
              description: Human readable error message in English.
              example: Example error message.
            messageParameters:
              type: array
              description: >
                In case an error message is parametrized, the parameter names
                and values are returned for, e.g., localization purposes. The
                parametrized error messages are defined at the operation error
                response descriptions in this API specification. Parameters are
                denoted by named placeholders '{\<parameter name\>}' in the 
                message specifications. At runtime, returned message
                placeholders are substituted by actual parameter values.
              items:
                type: object
                description: Message parameter
                properties:
                  name:
                    type: string
                    description: >-
                      Name of message parameter as specified in parametrized
                      error message.
                  value:
                    type: string
                    description: >-
                      Value of message parameter as substituted in returned
                      error message.
              example:
                - name: exampleParameterName
                  value: '100'
  fileDeleteRuleRequest:
    description: List of delete requests.
    type: array
    maxItems: 1
    items:
      type: object
      required:
        - assetId
        - deleteAfterDays
      properties:
        assetId:
          type: string
          description: unique Identifier for asset id
          example: '0fcd06e781dd4bb0b9bd271d648741aa'
          minLength: 32
          maxLength: 32
          pattern: "[a-f0-9]{32}"
        path:
          type: string
          description: path for file delete TTL rule
          example: '/folder1/folder2'
          maxLength: 365
          default: /
        deleteAfterDays:
          type: number
          description: number of days after last updated, from files will be deleted
          maxLength: 365
          minLength: 30
          default: 30
          example: 30
  fileDeleteRuleCreateResponse:
    description: List of delete requests.
    type: array
    maxItems: 1
    items:
      type: object
      properties:
        id:
          type: string
          format: uuid2
          description: unique Identifier for file delete (TTL) rule
          example: '0fcd06e7-81dd-4bb0-b9bd-271d648741aa'
          maxLength: 36
          minLength: 12
          pattern: "[a-z0-9-]{12,36}"
        assetId:
          type: string
          format: uuid2
          description: unique Identifier for asset
          example: '089336872ce342aba1a847f53d515dc7'
        path:
          type: string
          description: path for file delete TTL rule
          example: '/folder1/folder2'
          maxLength: 500
          default: /
        deleteAfterDays:
          type: number
          description: number of days after last updated, from files will be deleted
          maxLength: 500
          minLength: 1
          default: 180
          example: 30
        created:
          type: string
          example: "2023-03-15 12:29:31.0"
  fileDeleteRuleGetAllResponse:
    type: object
    required:
      - id
      - created
    properties:
      id:
        type: string
        format: uuid2
        description: unique Identifier for file delete (TTL) rule
        example: '0fcd06e7-81dd-4bb0-b9bd-271d648741aa'
        maxLength: 36
        minLength: 12
        pattern: "[a-z0-9-]{12,36}"
      assetId:
        type: string
        format: uuid2
        description: unique Identifier for asset
        example: '089336872ce342aba1a847f53d515dc7'
      path:
        type: string
        format: uuid2
        description: Rule applied on this path
        example: 'abc33/'
      deleteAfterDays:
        type: number
        description: delete after days
        example: 1
      state:
        type: string
        description: state for file delete TTL rule
        enum: [ "DELETED","ACTIVE","MARKED_FOR_DELETE" ]
        example: ACTIVE
      created:
        type: string
        description: date time when file delete (TTL) was created
        format: date-time
        example: "2020-03-01 09:12:28.110"
  fileDeleteRuleResponse:
    type: object
    required:
      - id
      - assetId
      - path
      - deleteAfterDays
    properties:
      id:
        type: string
        format: uuid2
        description: unique Identifier for file delete (TTL) rule
        example: '0fcd06e7-81dd-4bb0-b9bd-271d648741aa'
        maxLength: 36
        minLength: 12
        pattern: "[a-z0-9-]{12,36}"
      assetId:
        type: string
        description: unique Identifier for asset id
        example: '0fcd06e781dd4bb0b9bd271d648741aa'
        minLength: 32
        maxLength: 32
        pattern: "[a-f0-9]{32}"
      path:
        type: string
        description: path for file delete TTL rule
        example: '/folder1/folder2'
        maxLength: 500
        default: /
      deleteAfterDays:
        type: number
        description: number of days after last updated, from files will be deleted
        maxLength: 500
        minLength: 1
        default: 180
        example: 30
      state:
        type: string
        description: state for file delete TTL rule
        enum: [ "PENDING","ACTIVE","MARKED_FOR_DELETE" ]
        example: MARKED_FOR_DELETE
      created:
        type: string
        description: date time when file delete (TTL) was created
        format: date-time
        example: "2020-03-01 09:12:28.110"
  fileDeleteRulesPageResponse:
    type: object
    required:
      - fileDeleteRules
      - page
    properties:
      fileDeleteRules:
        $ref: '#/definitions/fileDeleteRuleGetAllResponse'
      page:
        $ref: '#/definitions/Page'

  fileDeleteRuleExecutionsResponseArray:
    type: array
    items:
      $ref: '#/definitions/fileDeleteRuleExecutionsResponse'
  fileDeleteRuleExecutionsResponse:
    type: object
    required:
      - executionId
      - timestamp
      - status
    properties:
      executionId:
        type: string
        format: uuid2
        description: unique Identifier for file delete (TTL) rule execution
        maxLength: 36
        minLength: 12
        pattern: "[a-z0-9-]{12,36}"
        example: '0fcd06e7-81dd-4bb0-b9bd-271d648741aa'
      timestamp:
        type: string
        description: time when the executions was started
        format: date-time
        example: "2020-06-01T09:12:28.110Z"
      noOfFilesDeleted:
        type: number
        description: total number of files that were deleted in this execution
        example: 10
      status:
        type: string
        description: status of execution
        enum: [ COMPLETED, IN_PROGRESS, FAILED ]
      msg:
        type: string
        description: description for the reason of failure execution.
  Page:
    type: object
    properties:
      size:
        type: integer
      totalElements:
        type: integer
      totalPages:
        type: integer
      number:
        type: integer
parameters:
  page:
    name: page
    in: query
    type: integer
    default: 0
    minimum: 0
    maximum: 50
    description: Specifies the requested page index
  size:
    name: size
    in: query
    type: integer
    default: 10
    minimum: 1
    maximum: 50
    description: Specifies the number of elements in a page
