openapi: 3.0.3
paths:
  /codeInventory:
    post:
      summary: Start creation of the code inventory report
      description: Schedule creation of a code inventory report with parameters specified in the request body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodeInventoryCreateReportRequest'
        required: true
      responses:
        '202':
          description: Scheduled report
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeInventoryReportResponse'
                  - properties:
                      state:
                        type: string
                        example: PROCESSING
                  - required:
                      - reportId
                      - userId
                      - state
                      - params
                      - requestTime
        '400':
          description: Failed report request
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeInventoryReportResponse'
                  - properties:
                      state:
                        type: string
                        example: FAILED
                      stateMessages:
                        description: Information why the report generation failed
                        type: array
                        items:
                          type: string
                  - required:
                      - state
                      - params
                      - stateMessages
      security:
        - ApiKey: [ ]
      tags:
        - Code Inventory Report
    get:
      summary: Gets a list of reports
      description: Gets a list of reports
      parameters:
        - $ref: '../crs_restapi_common.yaml#/components/parameters/afterToken'
        - $ref: '../crs_restapi_common.yaml#/components/parameters/limit'
        - $ref: '../crs_restapi_common.yaml#/components/parameters/userId'
        - $ref: '../crs_restapi_common.yaml#/components/parameters/reportName'
        - $ref: '../report/common.yaml#/components/parameters/reportState'
        - $ref: '../report/common.yaml#/components/parameters/reportRequestTimeFrom'
        - $ref: '../report/common.yaml#/components/parameters/reportRequestTimeTo'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../crs_restapi_common.yaml#/components/schemas/DataPage'
                  - properties:
                      data:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/CodeInventoryReportResponse'
                            - properties:
                                data:
                                  example: null
                                  type: array
                                  items:
                                    type: object
                                stateMessages:
                                  type: array
                                  example: null
                                  items:
                                    type: string
                            - required:
                                - reportId
                                - state
                                - params
                                - requestTime
                                - userId
          description: List of report descriptions
      security:
        - ApiKey: [ ]
      tags:
        - Code Inventory Report

  /codeInventory/{reportId}:
    get:
      summary: Gets the report by ID
      description: Gets the report by identifier
      parameters:
        - description: Report ID
          example: 1cc40ee6-87a7-4147-b02d-7d26ce0387d0
          in: path
          name: reportId
          required: true
          schema:
            type: string
        - description:
            Token to retrieve the next report page
            For correct pagination, need to use the 'afterToken' returned in the current response to get the next page of data.
          in: query
          name: afterToken
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Found report by ID
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeInventoryReportResponse'
                  - required:
                      - reportId
                      - state
                      - params
                      - userId
                      - requestTime
        '404':
          description: Report with such ID does not exist
          content:
            application/json:
              schema:
                type: string
                example: "Unknown report: 1cc40ee6-87a7-4147-b02d-7d26ce0387d0"
      security:
        - ApiKey: [ ]
      tags:
        - Code Inventory Report
    delete:
      summary: Deletes report by ID
      description: Deletes report by ID
      parameters:
        - description: Report ID
          example: 1cc40ee6-87a7-4147-b02d-7d26ce0387d0
          in: path
          name: reportId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Report deleted successfully
      security:
        - ApiKey: [ ]
      tags:
        - Code Inventory Report

components:
  schemas:
    CodeInventoryCreateReportRequest:
      description: Request to create code inventory report
      allOf:
        - $ref: '#/components/schemas/CodeInventoryReportParameters'
        - $ref: '../report/common.yaml#/components/schemas/ReportName'
      type: object

    CodeInventoryData:
      description: >
        List of sources / classes / methods matching the provided request filter.
      type: array
      items:
        properties:
          sourceName:
            type: string
            description: 'Name of the source'
            example: 'myapp.jar'
          className:
            type: string
            description: 'Name of the class'
            example: 'com/company/firstclass'
          methodName:
            type: string
            description: 'Name of the method'
            example: 'getHost(java/lang/String)'
          firstSeen:
            description: 'When was the method first seen'
            type: string
            example: '2023-07-13T16:12:51.181'
          lastSeen:
            type: string
            description: 'When was the method last seen'
            example: '2023-07-14T11:10:01.112'
          AppEnv:
            type: string
            description: 'AppEnv value used to specify the customer domain'
            example: 'abc'
          tags:
            description: 'List of tags used when starting VMs (excluding AppEnv). For the time being, the List of returned tags is empty since no other tags are whitelisted.'
            type: array
            items:
              type: string
            example:
              - app:credit-service,
              - owner:finance-team

    CodeInventoryReportParameters:
      description: Request to create code inventory report
      properties:
        filter:
          description: >-
            Filter conditions, there is a logical AND operator between each
            condition. There is implicitly used LIKE operator. If yor filter contains filter
            methodName:get result contains all methods with name contains "get" (e.g. getName, mygetter, ...)
          example:
            - sourceName CONTAINS 'myapp.jar'
            - className CONTAINS 'com/company/firstclass'
            - methodName CONTAINS 'mymethod'
            - AppEnv CONTAINS 'forwarder'
          items:
            type: string
          type: array
        use:
          description: Filter used, unused or all (used + unused) code
          type: string
          default: USED
          enum:
            - USED
            - UNUSED
            - ALL
        from:
          type: string
          title: |
            Period start, inclusive.
          default: "3m"
          allOf:
            - $ref: '../report/common.yaml#/components/schemas/TimeString'
        to:
          type: string
          title: |
            Period end, inclusive.
          default: "0d"
          allOf:
            - $ref: '../report/common.yaml#/components/schemas/TimeString'
      type: object

    CodeInventoryReportResponse:
      description: Code inventory report response
      properties:
        reportName:
          description: Name of the report.
          type: string
          example: "Report name"
        reportId:
          description: Report ID used to retrieve report data
          example: 1cc40ee6-87a7-4147-b02d-7d26ce0387d0
          type: string
        state:
          description: >-
            Report generation state. If the report could not be generated
            entirely but some pages were successfully generated, those pages
            will be available for retrieval.
          type: string
          example: PROCESSING
          enum:
            - PROCESSING
            - SUCCEEDED
            - FAILED
            - TIMED_OUT
        userId:
          description: User who requested the report generation
          example: test@azul.com
          type: string
        params:
          allOf:
            - $ref: '#/components/schemas/CodeInventoryReportParameters'
              # The below properties are not included into CodeInventoryCreateReportRequest schema,
              # but described here instead because they are filled by backend and never by client
            - properties:
                resolvedFrom:
                  description: >-
                    Added to params automatically by server, contains period start, inclusive, in ISO-8601 format.   
                    If `from` is relative, `resolvedFrom` contains its absolute value, resolved on server,
                    otherwise the same value as `from`
                  example: '2023-07-13T16:42:37.268'
                  type: string
                resolvedTo:
                  description: >-
                    Added to params automatically by server, contains period end, inclusive, in ISO-8601 format.   
                    If `to` is relative, `resolvedTo` contains its absolute value, resolved on server,
                    otherwise the same value as `to`
                  example: '2023-07-13T16:42:37.268'
                  type: string
        stateMessages:
          description: >-
            messages related to the report state; if the state is FAILED then it
            contain error description.
          example:
            - 1st message
            - 2nd message
          type: array
          items:
            type: string
        requestTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            was initiated.
          example: '2023-07-13T16:42:37.268'
          type: string
        startTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            creation was started.
          example: '2023-07-13T16:42:37.268'
          type: string
        finishTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            creation was finished.
          example: '2023-07-13T16:42:47.231'
          type: string
        data:
          $ref: '#/components/schemas/CodeInventoryData'
        totalCount:
          description: >-
            Total count of records in the report
          example: '35352'
          type: integer
        afterToken:
          description:
            Token to retrieve the next report page
            For correct pagination, need to use the 'afterToken' returned in the current response to get the next page of data.
          example: '2'
          type: string
      type: object

    CodeInventoryGetListOfReportsResponse:
      description: List of reports
      properties:
        data:
          description: |
            List of reports metadata
          items:
            $ref: '#/components/schemas/CodeInventoryReportInfoType'
          type: array
        afterToken:
          description:
            Token to retrieve the next report page
            For correct pagination, need to use the 'afterToken' returned in the current response to get the next page of data.
          example: '1683200412'
          type: string
      type: object

    CodeInventoryReportInfoType:
      description: >
        Metadata of a Code Inventory report requested earlier with 
        POST /report/codeInventory. Contains report ID, state and
        other details known about the report.
      properties:
        reportId:
          description: Report ID used to retrieve report data
          example: 1cc40ee6-87a7-4147-b02d-7d26ce0387d0
          type: string
        state:
          description: >-
            Report generation state. If the report could not be generated
            entirely but some pages were successfully generated, those pages
            will be available for retrieval.
          type: string
          example: SUCCEEDED
          enum:
            - PROCESSING
            - SUCCEEDED
            - FAILED
            - TIMED_OUT
        stateMessages:
          description: >-
            messages related to the report state; if the state is FAILED then it
            contain error description.
          example:
            - 1st message
            - 2nd message
          type: array
          items:
            type: string
        userId:
          description: User who requested the report generation
          example: test@azul.com
          type: string
        params:
          $ref: '#/components/schemas/CodeInventoryReportParameters'
        requestTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            was initiated.
          example: '2023-02-15T00:00:00.000'
          type: string
        startTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            creation was started.
          example: '2023-02-15T00:00:00.000'
          type: string
        finishTime:
          description: >-
            DateTime in ISO-8601 standard. The timestamp of the moment report
            creation was finished.
          example: '2023-02-15T00:00:00.000'
          type: string
      type: object
