docs/sections/apis/deployment-handler-API.yaml

# ================================================================================
# Copyright (c) 2017-2018 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=========================================================

---

swagger: '2.0'

info:
  version: "3.0.3"
  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: 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

      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

      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:
    post:
      tags:
        - "policy"
      description: policy update API consumed by policy-handler

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

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

      responses:
        200:
          description: deployment-handler always responds with ok to /policy before processing the request

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

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


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: stringified int that is autoincremented by policy-engine
        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"

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

    properties:
      catch_up:
        description: flag to indicate whether the request contains all the policies in PDP or not
        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

      errored_policies:
        description: |
          whether policy-engine returned an error on the policy.
          dictionary of (policy_id -> true).
          In example: replace additionalProp1,2,3 with policy_id1,2,3 values
        type: object
        default: {}
        additionalProperties:
          type: boolean

      errored_scopes:
        description: >
          on cartchup - list of policy scope_prefix values on wchich
          the policy-engine experienced an error other than not-found data.
        type: array
        items:
          type: string

      scope_prefixes:
        description: >
          on catchup - list of all scope_prefixes used by the policy-handler
          to retrieve the policies from policy-engine.
        type: array
        items:
          type: string