openapi-spec.yml

openapi: "3.0.3"
info:
  version: 0.5.4
  title: xOpera API
  description: A stateful xOpera API for orchestration environment (single user, single project, single deployment)
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
paths:
  /validate:
    post:
      summary: Validate a service template
      operationId: validate
      requestBody:
        description: Validation inputs and service template name.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidationInput"
      responses:
        "200":
          description: The validation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationResult"
        "500":
          description: There was an error starting the validation.
  /deploy:
    post:
      summary: Deploy a CSAR
      operationId: deploy
      requestBody:
        description: Deployment inputs and service template name.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeploymentInput"
      responses:
        "202":
          description: The deployment was successfully initiated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invocation"
        "500":
          description: There was an error starting the deployment.
  /undeploy:
    post:
      summary: Undeploy a deployment
      operationId: undeploy
      responses:
        "202":
          description: The undeploy operation was successfully initiated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invocation"
        "500":
          description: There was an error starting the undeploy operation.
  /outputs:
    get:
      summary: Fetch deployment outputs
      operationId: outputs
      responses:
        "200":
          description: The outputs of the deployment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentOutput"
        "404":
          description: No outputs exist for this deployment.
  /info:
    get:
      summary: Get information about the current opera environment
      operationId: info
      responses:
        "200":
          description: The opera environment operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Info"
        "500":
          description: General error.
  /package:
    post:
      summary: Generate a CSAR from a working directory.
      operationId: package
      requestBody:
        description: CSAR packaging parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PackagingInput"
      responses:
        "200":
          description: Packaging successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PackagingResult"
        "500":
          description: General error.
  /unpackage:
    post:
      summary: Unpackage a CSAR.
      operationId: unpackage
      requestBody:
        description: CSAR unpackaging parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnpackagingInput"
      responses:
        "200":
          description: Unpackaging successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationSuccess"
        "500":
          description: General error.
  /diff:
    post:
      summary: Do a diff
      operationId: diff
      requestBody:
        description: Diff inputs
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DiffRequest"
      responses:
        "200":
          description: Diff response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Diff"
        "500":
          description: There was an error performing the diff.
  /update:
    post:
      summary: Do an update
      operationId: update
      requestBody:
        description: Update inputs
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRequest"
      responses:
        "202":
          description: Update successfully initiated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invocation"
        "500":
          description: There was an error initiating the update.
  /notify/{trigger_name}:
    parameters:
      - name: trigger_name
        in: path
        required: true
        schema:
          type: string
    post:
      summary: Do a notification.
      operationId: notify
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
      responses:
        "200":
          description: Trigger triggered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationSuccess"
        "500":
          description: General error.
  /status:
    get:
      summary: Fetch the status of a deployment
      operationId: status
      responses:
        "200":
          description: Asynchronous operation status history.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvocationHistory"
  /status/{invocation_id}:
    parameters:
      - name: invocation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Fetch the status of a particular invocation.
      operationId: invocationStatus
      responses:
        "200":
          description: An invocation status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invocation"
        "404":
          description: No invocation with this id.
  /version:
    get:
      summary: Get current opera version
      operationId: version
      responses:
        "200":
          description: The opera environment operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Version"
        "500":
          description: General error.
components:
  schemas:
    ValidationInput:
      description: Input for validate command.
      type: object
      required:
        - service_template
      properties:
        inputs:
          type: object
        service_template:
          type: string
    DeploymentInput:
      description: Input for deploy command.
      type: object
      required:
        - service_template
      properties:
        inputs:
          type: object
        service_template:
          type: string
        clean_state:
          type: boolean
    DeploymentOutput:
      description: Free-form mapping of outputs.
      type: object
    Diff:
      description: A diff.
      type: object
      required:
        - added
        - changed
        - deleted
      properties:
        added:
          type: array
          items:
            type: string
        changed:
          type: object
        deleted:
          type: array
          items:
            type: string
    DiffRequest:
      description: A diff request.
      type: object
      required:
        - serviceTemplate
        - inputs
        - templateOnly
        - newServiceTemplateContents
      properties:
        serviceTemplate:
          description: The filename of the base service template.
          type: string
        inputs:
          type: object
        templateOnly:
          type: boolean
        newServiceTemplateContents:
          description: The contents of the new service template.
          type: string
          format: bytes
    Invocation:
      description: An invocation of the deployment.
      type: object
      required:
        - id
        - state
        - operation
        - timestamp
      properties:
        id:
          type: string
        state:
          $ref: "#/components/schemas/InvocationState"
        operation:
          $ref: "#/components/schemas/OperationType"
        timestamp:
          description: An ISO8601 timestamp of the invocation.
          type: string
        service_template:
          description: The service template used for the invocation.
          type: string
        inputs:
          description: Inputs provided for invocation.
          type: object
        clean_state:
          description: Whether a clean deployment was requested.
          type: boolean
        instance_state:
          description: State of the instances defined in service template.
          type: object
          additionalProperties:
            type: string
        exception:
          description: An internal xOpera error that occurred during the operation.
          type: string
        stdout:
          description: xOpera console output for operation.
          type: string
        stderr:
          description: xOpera error output for operation.
          type: string
    InvocationHistory:
      description: Invocation history ordered by timestamp ascending.
      type: array
      items:
        $ref: "#/components/schemas/Invocation"
    ValidationResult:
      description: A CSAR validation result.
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
        message:
          type: string
    Info:
      description: Information about an opera environment.
      type: object
      properties:
        service_template:
          type: string
        content_root:
          type: string
        inputs:
          type: object
        status:
          type: string
        csar_metadata:
          type: object
        service_template_metadata:
          type: object
        csar_valid:
          type: boolean
    InvocationState:
      type: string
      enum:
        - pending
        - in_progress
        - success
        - failed
    OperationType:
      type: string
      enum:
        - deploy
        - undeploy
        - notify
        - update
    OperationSuccess:
      description: A general success message.
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
        message:
          type: string
    PackagingInput:
      description: Packaging parameters.
      type: object
      required:
        - format
        - service_template_folder
      properties:
        output:
          type: string
        format:
          $ref: "#/components/schemas/PackagingFormat"
        service_template:
          type: string
        service_template_folder:
          type: string
    PackagingFormat:
      type: string
      enum:
        - zip
        - tar
    PackagingResult:
      description: A general success message.
      type: object
      required:
        - package_path
      properties:
        package_path:
          type: string
    UnpackagingInput:
      description: Unpackaging parameters.
      type: object
      required:
        - csar
      properties:
        destination:
          type: string
        csar:
          type: string
    UpdateRequest:
      description: Update request.
      type: object
      required:
        - inputs
        - newServiceTemplateContents
      properties:
        inputs:
          type: object
        newServiceTemplateContents:
          description: The contents of the new service template.
          type: string
          format: bytes
    Version:
      description: Information about opera version.
      type: string