openapi: 3.0.3
paths:
  /component:
    post:
      tags:
        - Component Report
      summary: Schedules generation of the report that includes components (name + version) detected by AVD
      description: |
        Schedules generation of the report that includes components (name + version) detected by AVD
        based on the provided filters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateComponentReportRequest'
      responses:
        '202':
          description: Scheduled report.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../../report/common.yaml#/components/schemas/Report'
                  - properties:
                      params:
                        allOf:
                          - $ref: '#/components/schemas/CreateComponentReportParameters'
                          - $ref: '../../report/common.yaml#/components/schemas/ResolvedFromAndToParameters'
                      state:
                        type: string
                        example: PROCESSING
                  - required:
                      - reportId
                      - state
                      - params
                      - userId
                      - requestTime
        '400':
          description: Information about invalid parameters used to generate a report.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../../report/common.yaml#/components/schemas/Report'
                  - properties:
                      params:
                        allOf:
                          - $ref: '#/components/schemas/CreateComponentReportParameters'
                          - $ref: '../../report/common.yaml#/components/schemas/ResolvedFromAndToParameters'
                      state:
                        type: string
                        example: FAILED
                      stateMessages:
                        description: Information why the report generation failed.
                        type: array
                        items:
                          type: string
                  - required:
                      - state
                      - params
                      - stateMessages

    get:
      tags:
        - Component Report
      summary: List of Component report descriptions
      description:
        Gets a list of component report descriptions (without report data).
      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':
          description: List of report descriptions.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../../crs_restapi_common.yaml#/components/schemas/DataPage'
                  - properties:
                      data:
                        type: array
                        items:
                          allOf:
                            - $ref: '../../report/common.yaml#/components/schemas/Report'
                            - properties:
                                data:
                                  example: null
                                  type: array
                                  items:
                                    type: object
                                stateMessages:
                                  type: array
                                  example: null
                                  items:
                                    type: string
                                params:
                                  allOf:
                                    - $ref: '#/components/schemas/CreateComponentReportParameters'
                                    - $ref: '../../report/common.yaml#/components/schemas/ResolvedFromAndToParameters'
                            - required:
                                - reportId
                                - state
                                - params
                                - userId
                                - requestTime

  /component/{reportId}:
    get:
      tags:
        - Component Report
      summary: Gets the component report by ID
      description: Gets the component report by identifier.
      parameters:
        - $ref: '../../report/common.yaml#/components/parameters/reportId'
        - $ref: '../../report/common.yaml#/components/parameters/afterToken'
      responses:
        '200':
          description: |
            List of report fields:
            
            | Field | Definition  | Description  |
            | ----- | ----- | ----- |
            | AppEnv | string, not null, 'UNDEFINED' if not specified | custom AppEnv tag value used to specify the customer domain |
            | componentName | string, not null, 'UNKNOWN' if not detected | name of the detected component |
            | componentVersion | string, not null, 'UNKNOWN' if not detected | detected version of the component |
            | firstSeen | ISO-8601 string, not null, immutable | date and time of first usage of a specific AppEnv tag |
            | lastSeen | ISO-8601 string, not null, mutable | date and time of last usage of a specific AppEnv tag |
            | tags | object, nullable, contains immutable 'tag:value' pairs | list of additional tags associated with a specific AppEnv, expanded at tags merging stage |

          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../../report/common.yaml#/components/schemas/Report'
                  - properties:
                      params:
                        allOf:
                          - $ref: '#/components/schemas/CreateComponentReportParameters'
                          - $ref: '../../report/common.yaml#/components/schemas/ResolvedFromAndToParameters'
                  - 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"
    delete:
      tags:
        - Component Report
      summary: Deletes the component report by ID
      description:
        Deletes the component report by identifier.
      security:
        - ApiKey: [ ]
      parameters:
        - $ref: '../../report/common.yaml#/components/parameters/reportId'
      responses:
        '204':
          description: Report deleted successfully.

components:
  schemas:
    CreateComponentReportRequest:
      description: Request to create component report.
      allOf:
        - $ref: '#/components/schemas/CreateComponentReportParameters'
        - $ref: '../../report/common.yaml#/components/schemas/ReportName'
      type: object

    CreateComponentReportParameters:
      description: Parameters used to generate a component report.
      type: object
      properties:
        filter:
          description: |
            List of available filter operations:
            
            | Operand | Fields with which this operand can be used |
            | ----- | ----- |
            | = | AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx |
            | != | AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx |
            | = null | tags.A, tags.B, tags.xxx |
            | != null | tags.A, tags.B, tags.xxx |
            | IN ('A', ...) | AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx |
            | CONTAINS 'A' | AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx |
            | <=, >=, <, > | componentVersion |
            
            Note: 
            - range filtering (>/>=/</<=) on string literals works based on their lexicographical (alphabetical) order;
            - string literal must be used with quotes: `'` or `"`
          type: array
          items:
            type: string
          example: [
            "AppEnv != 'UNDEFINED'",
            "componentVersion > '2'",
            "componentName CONTAINS 'log4j'"
          ]

        sortBy:
          description: |
            List of available fields that can be used for sorting:
            - AppEnv
            - componentName
            - componentVersion
            - firstSeen
            - lastSeen
            
            Default sorting (order matters and applies from top to bottom):
            - AppEnv = ASC
            - componentName = ASC
            - componentVersion = DESC
            
            **Format**: `<property_name>=<sort_order>`
            
            Sort order values:
            - `ASC` - ascending
            - `DESC` - descending
            
            Note:
            - order matters and applies from the first condition to the last in the list provided
          type: array
          example: [ "componentName=ASC", "componentVersion=DESC" ]
          items:
            type: string

        from:
          type: string
          title: |
            Relative or absolute time to get detected components based on VMs 
            that started or continued to run after (or equal to) the provided time.
          default: "3m"
          allOf:
            - $ref: '../../report/common.yaml#/components/schemas/TimeString'
        to:
          type: string
          title: |
            Relative or absolute time to get detected components based on VMs 
            that were started before (or equal to) the provided time.
          default: "0d"
          allOf:
            - $ref: '../../report/common.yaml#/components/schemas/TimeString'
