path: root/deployment-handler-API.yaml

# ================================================================================
# Copyright (c) 2017-2020 AT&T Intellectual Property. All rights reserved.
# ================================================================================
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ============LICENSE_END=========================================================
#
# ECOMP is a trademark and service mark of AT&T Intellectual Property.
---

swagger: '2.0'

info:
  version: "5.1.0"
  title: "deployment-handler API"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  description: |
    High-level API for deploying/undeploying composed DCAE services using Cloudify Manager.

tags:
  - name: "info"
    description: "version and links"
  - name: "dcae-deployments"
    description: "operations on dcae-deployments"
  - name: "policy"
    description: "policy update API consumed by policy-handler and debug API to find policies on components"

paths:
  /:
    get:
      tags:
        - "info"
      description: Returns version information and links to API operations
      produces:
        - "application/json"
      responses:

        200:
          description: Success
          schema:
            title: DispatcherInfo
            type: object
            properties:
              apiVersion:
                type: string
                description: |
                  version of API supported by this server
              serverVersion:
                type: string
                description: |
                  version of software running on this server
              links:
                type: object
                description: |
                  Links to API resources
                properties:
                  info:
                    type: string
                    description: |
                      path for the server information endpoint
                  events:
                    type: string
                    description: |
                      path for the events endpoint

  /dcae-deployments:
    get:
      tags:
        - "dcae-deployments"
      description: |
        List service deployments known to the orchestrator, optionally restricted to a single service type

      parameters:
        - name: serviceTypeId
          description: |
            Service type identifier for the type whose deployments are to be listed
          type: string
          in: query
          required: false

      responses:

        200:
          description: |
            Success. (Note that if no matching deployments are found, the request is still a success; the
            deployments array is empty in that case.)
          schema:
            $ref: "#/definitions/DCAEDeploymentsListResponse"

        500:
          description: |
            Problem on the server side.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"
        502:
          description: |
            Error reported to the dispatcher by a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        504:
          description: |
            Error communicating with a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

  /dcae-deployments/{deploymentId}:
    put:
      tags:
        - "dcae-deployments"
      description: |
        Request deployment of a DCAE service

      consumes:
        - application/json
      produces:
        - application/json

      parameters:
        - name: deploymentId
          description: |
            Unique deployment identifier assigned by the API client.
          in: path
          type: string
          required: true
        - name: cfy_tenant_name
          description: |
            Tenant Name in Cloudify. Optional, if not specified, "default_tenant" will be used.
          in: query
          type: string
          required: false

        - name: body
          in: body
          schema:
            $ref: "#/definitions/DCAEDeploymentRequest"
          required: true

      responses:

        202:
          description: |
            Success:  The content that was posted is valid, the dispatcher has
              found the needed blueprint, created an instance of the topology in the orchestrator,
              and started an installation workflow.
          schema:
            $ref: "#/definitions/DCAEDeploymentResponse"

        400:
          description: |
            Bad request: See the message in the response for details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        409:
          description: |
            A service with the specified deployment Id already exists.  Using PUT to update the service is not a supported operation.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        415:
          description: |
            Bad request: The Content-Type header does not indicate that the content is
            'application/json'
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        500:
          description: |
            Problem on the server side.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        502:
          description: |
            Error reported to the dispatcher by a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        504:
          description: |
            Error communicating with a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

    delete:
      tags:
        - "dcae-deployments"
      description: |
        Uninstall the DCAE service and remove all associated data from the orchestrator.

      parameters:
        - name: deploymentId
          description: |
            Deployment identifier for the service to be uninstalled.
          in: path
          type: string
          required: true
        - name: force_uninstall
            description: |
              Set the "force" boolean flag when performing an uninstall in Cloudify. Optional, if not specified, "false" will be used.
            in: query
            type: string
            required: false

      responses:

        202:
          description: |
            Success:  The dispatcher has initiated the uninstall operation.
          schema:
            $ref: "#/definitions/DCAEDeploymentResponse"

        400:
          description: |
            Bad request: See the message in the response for details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        500:
          description: |
            Problem on the server side.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        502:
          description: |
            Error reported to the dispatcher by a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        504:
          description: |
            Error communicating with a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

  /dcae-deployments/{deploymentId}/operation/{operationId}:
    get:
      tags:
        - "dcae-deployments"
      description: |
        Get status of a deployment operation
      parameters:
        - name: deploymentId
          in: path
          type: string
          required: true
        - name: operationId
          in: path
          type: string
          required: true
        - name: cfy_tenant_name
          description: |
            Tenant Name in Cloudify. Optional, if not specified, "default_tenant" will be used.
          in: query
          type: string
          required: false

      responses:

        200:
          description: Status information retrieved successfully
          schema:
            $ref: "#/definitions/DCAEOperationStatusResponse"

        404:
          description: The operation information does not exist (possibly because the service has been uninstalled and deleted).
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        500:
          description: |
            Problem on the server side.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        502:
          description: |
            Error reported to the dispatcher by a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        504:
          description: |
            Error communicating with a downstream system.  See the message
            in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

  /policy:
    get:
      tags:
        - "policy"
      description: debug API to find deployed policies and policy-filters on components
      produces:
        - application/json

      parameters:
        - name: cfy_tenant_name
          description: |
            Tenant Name in Cloudify. Optional, if not specified, "default_tenant" will be used.
          in: query
          type: string
          required: false

      responses:
        200:
          description: policies and policy_filters found on deployed components
          schema:
            $ref: "#/definitions/DCAEPoliciesResponse"

    put:
      tags:
        - "policy"
      description: policy update API consumed by policy-handler

      consumes:
        - application/json
      produces:
        - application/json

      parameters:
        - name: cfy_tenant_name
          description: |
            Tenant Name in Cloudify. Optional, if not specified, "default_tenant" will be used.
          in: query
          type: string
          required: false
        - name: body
          in: body
          schema:
            $ref: "#/definitions/DCAEPolicyUpdateRequest"
          required: true

      responses:
        200:
          description: deployment-handler always responds with ok to /policy before processing the request
          schema:
            $ref: "#/definitions/DCAEPolicyUpdateResponse"

  /policy/components:
    get:
      tags:
        - "policy"
      description: debug API to find policies on components
      produces:
        - application/json

      parameters:
        - name: cfy_tenant_name
          description: |
            Tenant Name in Cloudify. Optional, if not specified, "default_tenant" will be used.
          in: query
          type: string
          required: false

      responses:
        200:
          description: deployment-handler found components with or without policies in cloudify

  /healthcheck:
    get:
      tags:
        - "healthcheck"
      description: Returns version information and links to API operations thus checking internal health of deployment handler
      produces:
        - "application/json"
      responses:

        200:
          description: Success
          schema:
            title: DispatcherInfo
            type: object
            properties:
              apiVersion:
                type: string
                description: |
                  version of API supported by this server
              serverVersion:
                type: string
                description: |
                  version of software running on this server
              links:
                type: object
                description: |
                  Links to API resources
                properties:
                  info:
                    type: string
                    description: |
                      path for the server information endpoint
                  events:
                    type: string
                    description: |
                      path for the events endpoint

  /servicehealth:
    get:
      tags:
        - "servicehealth"
      description: checks deployment handler's dependencies/external interfaces' health; namely inventory and cloudify
      produces:
        - "application/json"
      responses:

        200:
          description: Success
          schema:
            title: DeploymentHanlderServiceHealth
            type: object
            properties:
              requestId:
                type: string
                description: |
                  Internal request id (for tracking purposes)
              status:
                type: string
                description: |
                  Status of the API call: OK or NOT OK

        500:
          description: |
            Problem on the server side.  See the message in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        502:
          description: |
            Error reported to the dispatcher by a downstream system.  See the message in the response for more details.
          schema:
            $ref: "#/definitions/DCAEErrorResponse"

        503:
          description: |
            Error communicating with a downstream system(s). Inventory/Cloudify service is not available.

definitions:

  DCAEDeploymentRequest:
    description: |
      Request for deploying a DCAE service.
    type:
      object
    required: [serviceTypeId]

    properties:

      serviceTypeId:
        description: |
          The service type identifier (a unique ID assigned by DCAE inventory) for the service to be deployed.
        type: string

      inputs:
        description: |
          Object containing inputs needed by the service blueprint to create an instance of the service.
          Content of the object depends on the service being deployed.
        type: object

  DCAEDeploymentResponse:
    description: |
      Response body for a PUT or DELETE to /dcae-deployments/{deploymentId}
    type: object

    required: [requestId, links]

    properties:
      requestId:
        type: string
        description: |
          Unique identifier for the request
      links:
        description: |
          Links that the API client can access.
        type: object
        properties:
          self:
            type: string
            description: |
              Link used to retrieve information about the service being deployed
          status:
            type: string
            description:
              Link used to retrieve information about the status of the installation workflow

  DCAEOperationStatusResponse:
    description: |
      Response body for a request for status of an installation or uninstallation operation.
    type: object

    required: [requestId, operationType, status]

    properties:
      requestId:
        type: string
        description: |
          A unique identifier assigned to the request.  Useful for tracing a request through logs.
      operationType:
        description: |
          Type of operation being reported on. ("install" or "uninstall")
        type: string
      status:
        description: |
          Status of the installation or uninstallation operation.  Possible values are "processing",
          "succeeded", and "failed"
        type: string
      error:
        description: |
          If status is "failed", this field will be present and contain additional information about the reason the operation failed.
        type: string
      links:
        description: |
         If the operation succeeded, links that the client can follow to take further action.  Note that a successful "uninstall" operation removes the DCAE service instance completely, so there are no possible further actions, and no links.
        type: object
        properties:
          self:
            type: string
            description: |
              Link used to retrieve information about the service.
          uninstall:
            type: string
            description:
              Link used to trigger an "uninstall" operation for the service.  (Use the DELETE method.)

  DCAEErrorResponse:
    description: |
      Object reporting an error.
    type:
      object
    required: [status]

    properties:
      status:
        description: HTTP status code for the response
        type: integer

      message:
        description: Human-readable description of the reason for the error
        type: string

  DCAEDeploymentsListResponse:
    description: |
      Object providing a list of deployments
    type: object
    required: [requestId, deployments]

    properties:
      requestId:
        type: string
        description: |
          Unique identifier for the request
      deployments:
        type: array
        items:
          type: object
          properties:
            href:
              type: string
              description: |
                  URL for the service deployment

  DCAEPolicyBody:
    description: policy_body - the whole object received from policy-engine
    type: object
    required:
      - policyName
      - policyVersion
      - config
    properties:
      policyName:
        description: unique policy name that contains the version and extension
        type: string
      policyVersion:
        description: semver that is provided to policy-engine on policy modification
        type: string
      config:
        description: the policy-config - the config data provided by policy owner
        type: object

  DCAEPolicy:
    description: policy object
    type: object
    required:
      - policy_id
      - policy_body
    properties:
      policy_id:
        description: unique identifier of policy regardless of its version
        type: string
      policy_body:
        $ref: "#/definitions/DCAEPolicyBody"

  DCAEPolicyMatchToFilters:
    description:  |
      collection of policy-filter-ids the policy matches to
      dictionary of (policy_filter_id -> true)
      In example: replace additionalProp1,2,3 with policy_filter_id1,2,3 values
    type: object
    default: {}
    additionalProperties:
      type: boolean

  DCAEPolicyUpdateRequest:
    description: request to update policies on DCAE components.
    type: object
    required:
      - catch_up
      - latest_policies
      - removed_policies
      - policy_filter_matches

    properties:
      catch_up:
        description: indicates whether the request contains the policies for catch_up event
        type: boolean
        default: false

      latest_policies:
        description: |
          dictionary of (policy_id -> DCAEPolicy object).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          $ref: "#/definitions/DCAEPolicy"

      removed_policies:
        description: |
          whether policy was removed from policy-engine.
          dictionary of (policy_id -> true).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          type: boolean

      policy_filter_matches:
        description: |
          whether latest policy matches to policy-filters
          dictionary of (policy_id -> DCAEPolicyMatchToFilters).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          $ref: "#/definitions/DCAEPolicyMatchToFilters"

  DCAEPolicyUpdateResponse:
    description: response to update policies on DCAE components.
    type: object
    properties:
      server_instance_uuid:
        description: uuid of the deployment-handler instance
        type: string


  DCAEPolicyTopInfo:
    description: |
      single policy-info object that contains policy_id
      and the collection of policy-versions along with the indicator
      that at least one deployment that contains that policy is busy with execution
    type: object
    required:
      - policy_id
      - policy_versions
      - pending_update

    properties:
      policy_id:
        description: unique identifier of policy regardless of its version
        type: string
      policy_versions:
        description: |
          dictionary of (policy_version -> true).
          In example: replace additionalProp1,2,3 with "1","2","3" keys
          For instance {"1":true, "3":true}
        type: object
        default: {}
        additionalProperties:
          type: boolean
      pending_update:
        description: |
          boolean indicating whether there are any executions are in place
          for any of deployments that have this policy
        type: boolean

  DCAEPolicyFilter:
    description: single policy-filter object
    type: object
    required:
      - policy_filter_id
      - policy_filter
      - pending_update

    properties:
      policy_filter_id:
        description: unique identifier of deployed policy-filter
        type: string
      policy_filter:
        description: policy-filter contains fields used in /getConfig on policy-engine API
        type: object
        properties:
          policyName:
            description: string or regular expression to match policyName in policy-engine
            type: string
          unique:
            description: whether expected unique or not policy in policy-engine
            type: boolean
          onapName:
            description: name of ONAP system for the policy in policy-engine
            type: string
          configName:
            description: name of ONAP system for the policy in policy-engine
            type: string
          configAttributes:
            description: dictionary of (key -> value) pairs used to match the policy
            type: object
            default: {}
            additionalProperties:
              type: string

      pending_update:
        description: |
          boolean indicating whether there are any executions are in place
          for any of deployments that have this policy
        type: boolean

  DCAEPoliciesResponse:
    description: response to get /policy
    type: object
    required:
      - server_instance_uuid
      - policies
      - policy_filters

    properties:
      server_instance_uuid:
        description: uuid of the deployment-handler instance
        type: string

      policies:
        description: |
          dictionary of (policy_id -> DCAEPolicyTopInfo object).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          $ref: "#/definitions/DCAEPolicyTopInfo"

      policy_filters:
        description: |
          dictionary of (policy_filter_id -> DCAEPolicyFilter object).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          $ref: "#/definitions/DCAEPolicyFilter"