openapi: 3.0.3
paths:

  /instance/{vmId}:
    get:
      tags:
        - VM instance
      summary: Get VM instance
      description: Gets VM instance model by ID
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: VM instance with requested ID
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '../crs_restapi_common.yaml#/components/schemas/VMInstance'
                  - required:
                      - vmId
                      - state
                      - inventory
                      - startTime
                      - lastHeardTime

        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string

  /instance/{vmId}/annotations:
    get:
      tags:
        - VM instance
      summary: Get VM instance annotations
      description: Get annotations of the VM instance with requested ID
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: VM instance annotations
          content:
            application/json:
              schema:
                type: object
                description: VM instance annotations with free form schema
                properties:
                  "com.azul.crs.application":
                    description: Application detected by VM instance data reported to AVD
                    type: string
                  "com.azul.crs.cve.impact.v2":
                    $ref: '../crs_restapi_common.yaml#/components/schemas/CVEImpact2'
                  "com.azul.crs.application.components":
                    description: Components detected by VM instance data reported to AVD
                    type: array
                    items:
                      $ref: '../crs_restapi_common.yaml#/components/schemas/ComponentUsage'
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string

  /instance/{vmId}/tags:
    get:
      tags:
        - VM instance
      summary: Get VM instance tags
      description:
        Gets array of VM instance tags. Tags are `key=value` items without spaces, tabs, commas and semicolons inside.
        Tags can be associated with VM instance on app execution or later over API calls. Tags are used to group
        or search VM instances via CQL.
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          example: 9f8898ea-0be5-45e4-bcfd-c4259c1ffd2b
          schema:
            type: string
      responses:
        '200':
          description: Tags of VM instance with requested ID
          content:
            application/json:
              schema:
                type: array
                example: [ "app=loyalty", "team=offers" ]
                items:
                  type: string
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string
    post:
      tags:
        - VM instance
      summary: Add tag to VM instance
      description: |
        Adds one tag to VM instance and reports whether suggested tag has been added or already exists with the specified value.

        The tag name must consist of the following characters: `A-Z`, `a-z`, `0-9`,`_.-`
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          example: 9f8898ea-0be5-45e4-bcfd-c4259c1ffd2b
          schema:
            type: string
        - name: tag
          in: query
          required: true
          example: zone
          schema:
            type: string
        - name: value
          in: query
          required: true
          example: us-oregon
          schema:
            type: string
      responses:
        '200':
          description: True when tag is added to VM instance, false when tag existed already
          content:
            application/json:
              schema:
                type: boolean
        '400':
          description: Tag name or tag value is not provided or empty
          content:
            application/json:
              schema:
                type: string
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string
    put:
      tags:
        - VM instance
      summary: Set VM instance tags
      description: |
        Sets array of `key=value` strings as VM instance tags.
        Previous tags of VM instance, if any, are all replaced with new ones.

        The tag name must consist of the following characters: `A-Z`, `a-z`, `0-9`,`_.-`
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          example: 9f8898ea-0be5-45e4-bcfd-c4259c1ffd2b
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              example: [ "app=loyalty", "team=offers" ]
              items:
                type: string
      responses:
        '204':
          description: VM instance tags are set
        '400':
          description: Invalid tags provided
          content:
            application/json:
              schema:
                type: string
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string
    delete:
      tags:
        - VM instance
      summary: Delete VM instance tags
      description: Deletes all tags of VM instance
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          example: 9f8898ea-0be5-45e4-bcfd-c4259c1ffd2b
          schema:
            type: string
      responses:
        '204':
          description: Tags of VM instance with requested ID deleted
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string

  /instance/{vmId}/tags/{tag}:
    delete:
      tags:
        - VM instance
      summary: Delete VM instance tag
      description: |
        Deletes specified tag of VM instance and reports whether it was deleted.

        The tag name must consist of the following characters: `A-Z`, `a-z`, `0-9`,`_.-`
      security:
        - ApiKey: [ ]
      parameters:
        - name: vmId
          in: path
          required: true
          example: 9f8898ea-0be5-45e4-bcfd-c4259c1ffd2b
          schema:
            type: string
        - name: tag
          in: path
          required: true
          example: zone
          schema:
            type: string
      responses:
        '200':
          description: True when tag of VM instance is deleted, false if tag not found
          content:
            application/json:
              schema:
                type: boolean
        '400':
          description: Invalid tag name provided
          content:
            application/json:
              schema:
                type: string
        '404':
          description: VM instance with requested ID not found
          content:
            application/json:
              schema:
                type: string