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

   1 # ================================================================================
   2 # Copyright (c) 2017-2018 AT&T Intellectual Property. All rights reserved.
   3 # ================================================================================
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 # ============LICENSE_END=========================================================
  16 #
  17 # ECOMP is a trademark and service mark of AT&T Intellectual Property.
  18 ---
  19
  20 swagger: '2.0'
  21
  22 info:
  23   version: "4.1.0"
  24   title: "deployment-handler API"
  25   license:
  26     name: "Apache 2.0"
  27     url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  28   description: |
  29     High-level API for deploying/undeploying composed DCAE services using Cloudify Manager.
  30
  31 tags:
  32   - name: "info"
  33     description: "version and links"
  34   - name: "dcae-deployments"
  35     description: "operations on dcae-deployments"
  36   - name: "policy"
  37     description: "policy update API consumed by policy-handler and debug API to find policies on components"
  38
  39 paths:
  40   /:
  41     get:
  42       tags:
  43         - "info"
  44       description: Returns version information and links to API operations
  45       produces:
  46         - "application/json"
  47       responses:
  48
  49         200:
  50           description: Success
  51           schema:
  52             title: DispatcherInfo
  53             type: object
  54             properties:
  55               apiVersion:
  56                 type: string
  57                 description: |
  58                   version of API supported by this server
  59               serverVersion:
  60                 type: string
  61                 description: |
  62                   version of software running on this server
  63               links:
  64                 type: object
  65                 description: |
  66                   Links to API resources
  67                 properties:
  68                   info:
  69                     type: string
  70                     description: |
  71                       path for the server information endpoint
  72                   events:
  73                     type: string
  74                     description: |
  75                       path for the events endpoint
  76
  77   /dcae-deployments:
  78     get:
  79       tags:
  80         - "dcae-deployments"
  81       description: |
  82         List service deployments known to the orchestrator, optionally restricted to a single service type
  83
  84       parameters:
  85         - name: serviceTypeId
  86           description: |
  87             Service type identifier for the type whose deployments are to be listed
  88           type: string
  89           in: query
  90           required: false
  91
  92       responses:
  93
  94         200:
  95           description: |
  96             Success. (Note that if no matching deployments are found, the request is still a success; the
  97             deployments array is empty in that case.)
  98           schema:
  99             $ref: "#/definitions/DCAEDeploymentsListResponse"
 100
 101         500:
 102           description: |
 103             Problem on the server side.  See the message
 104             in the response for more details.
 105           schema:
 106             $ref: "#/definitions/DCAEErrorResponse"
 107         502:
 108           description: |
 109             Error reported to the dispatcher by a downstream system.  See the message
 110             in the response for more details.
 111           schema:
 112             $ref: "#/definitions/DCAEErrorResponse"
 113
 114         504:
 115           description: |
 116             Error communicating with a downstream system.  See the message
 117             in the response for more details.
 118           schema:
 119             $ref: "#/definitions/DCAEErrorResponse"
 120
 121   /dcae-deployments/{deploymentId}:
 122     put:
 123       tags:
 124         - "dcae-deployments"
 125       description: |
 126         Request deployment of a DCAE service
 127
 128       consumes:
 129         - application/json
 130       produces:
 131         - application/json
 132
 133       parameters:
 134         - name: deploymentId
 135           description: |
 136             Unique deployment identifier assigned by the API client.
 137           in: path
 138           type: string
 139           required: true
 140
 141         - name: body
 142           in: body
 143           schema:
 144             $ref: "#/definitions/DCAEDeploymentRequest"
 145           required: true
 146
 147       responses:
 148
 149         202:
 150           description: |
 151             Success:  The content that was posted is valid, the dispatcher has
 152               found the needed blueprint, created an instance of the topology in the orchestrator,
 153               and started an installation workflow.
 154           schema:
 155             $ref: "#/definitions/DCAEDeploymentResponse"
 156
 157         400:
 158           description: |
 159             Bad request: See the message in the response for details.
 160           schema:
 161             $ref: "#/definitions/DCAEErrorResponse"
 162
 163         409:
 164           description: |
 165             A service with the specified deployment Id already exists.  Using PUT to update the service is not a supported operation.
 166           schema:
 167             $ref: "#/definitions/DCAEErrorResponse"
 168
 169         415:
 170           description: |
 171             Bad request: The Content-Type header does not indicate that the content is
 172             'application/json'
 173           schema:
 174             $ref: "#/definitions/DCAEErrorResponse"
 175
 176         500:
 177           description: |
 178             Problem on the server side.  See the message
 179             in the response for more details.
 180           schema:
 181             $ref: "#/definitions/DCAEErrorResponse"
 182
 183         502:
 184           description: |
 185             Error reported to the dispatcher by a downstream system.  See the message
 186             in the response for more details.
 187           schema:
 188             $ref: "#/definitions/DCAEErrorResponse"
 189
 190         504:
 191           description: |
 192             Error communicating with a downstream system.  See the message
 193             in the response for more details.
 194           schema:
 195             $ref: "#/definitions/DCAEErrorResponse"
 196
 197     delete:
 198       tags:
 199         - "dcae-deployments"
 200       description: |
 201         Uninstall the DCAE service and remove all associated data from the orchestrator.
 202
 203       parameters:
 204         - name: deploymentId
 205           description: |
 206             Deployment identifier for the service to be uninstalled.
 207           in: path
 208           type: string
 209           required: true
 210
 211       responses:
 212
 213         202:
 214           description: |
 215             Success:  The dispatcher has initiated the uninstall operation.
 216           schema:
 217             $ref: "#/definitions/DCAEDeploymentResponse"
 218
 219         400:
 220           description: |
 221             Bad request: See the message in the response for details.
 222           schema:
 223             $ref: "#/definitions/DCAEErrorResponse"
 224
 225         500:
 226           description: |
 227             Problem on the server side.  See the message
 228             in the response for more details.
 229           schema:
 230             $ref: "#/definitions/DCAEErrorResponse"
 231
 232         502:
 233           description: |
 234             Error reported to the dispatcher by a downstream system.  See the message
 235             in the response for more details.
 236           schema:
 237             $ref: "#/definitions/DCAEErrorResponse"
 238
 239         504:
 240           description: |
 241             Error communicating with a downstream system.  See the message
 242             in the response for more details.
 243           schema:
 244             $ref: "#/definitions/DCAEErrorResponse"
 245
 246   /dcae-deployments/{deploymentId}/operation/{operationId}:
 247     get:
 248       tags:
 249         - "dcae-deployments"
 250       description: |
 251         Get status of a deployment operation
 252       parameters:
 253         - name: deploymentId
 254           in: path
 255           type: string
 256           required: true
 257         - name: operationId
 258           in: path
 259           type: string
 260           required: true
 261
 262       responses:
 263
 264         200:
 265           description: Status information retrieved successfully
 266           schema:
 267             $ref: "#/definitions/DCAEOperationStatusResponse"
 268
 269         404:
 270           description: The operation information does not exist (possibly because the service has been uninstalled and deleted).
 271           schema:
 272             $ref: "#/definitions/DCAEErrorResponse"
 273
 274         500:
 275           description: |
 276             Problem on the server side.  See the message
 277             in the response for more details.
 278           schema:
 279             $ref: "#/definitions/DCAEErrorResponse"
 280
 281         502:
 282           description: |
 283             Error reported to the dispatcher by a downstream system.  See the message
 284             in the response for more details.
 285           schema:
 286             $ref: "#/definitions/DCAEErrorResponse"
 287
 288         504:
 289           description: |
 290             Error communicating with a downstream system.  See the message
 291             in the response for more details.
 292           schema:
 293             $ref: "#/definitions/DCAEErrorResponse"
 294
 295   /policy:
 296     post:
 297       tags:
 298         - "policy"
 299       description: policy update API consumed by policy-handler
 300
 301       consumes:
 302         - application/json
 303       produces:
 304         - application/json
 305
 306       parameters:
 307         - name: body
 308           in: body
 309           schema:
 310             $ref: "#/definitions/DCAEPolicyRequest"
 311           required: true
 312
 313       responses:
 314         200:
 315           description: deployment-handler always responds with ok to /policy before processing the request
 316
 317   /policy/components:
 318     get:
 319       tags:
 320         - "policy"
 321       description: debug API to find policies on components
 322       produces:
 323         - application/json
 324
 325       responses:
 326         200:
 327           description: deployment-handler found components with or without policies in cloudify
 328
 329
 330 definitions:
 331
 332   DCAEDeploymentRequest:
 333     description: |
 334       Request for deploying a DCAE service.
 335     type:
 336       object
 337     required: [serviceTypeId]
 338
 339     properties:
 340
 341       serviceTypeId:
 342         description: |
 343           The service type identifier (a unique ID assigned by DCAE inventory) for the service to be deployed.
 344         type: string
 345
 346       inputs:
 347         description: |
 348           Object containing inputs needed by the service blueprint to create an instance of the service.
 349           Content of the object depends on the service being deployed.
 350         type: object
 351
 352   DCAEDeploymentResponse:
 353     description: |
 354       Response body for a PUT or DELETE to /dcae-deployments/{deploymentId}
 355     type: object
 356
 357     required: [requestId, links]
 358
 359     properties:
 360       requestId:
 361         type: string
 362         description: |
 363           Unique identifier for the request
 364       links:
 365         description: |
 366           Links that the API client can access.
 367         type: object
 368         properties:
 369           self:
 370             type: string
 371             description: |
 372               Link used to retrieve information about the service being deployed
 373           status:
 374             type: string
 375             description:
 376               Link used to retrieve information about the status of the installation workflow
 377
 378   DCAEOperationStatusResponse:
 379     description: |
 380       Response body for a request for status of an installation or uninstallation operation.
 381     type: object
 382
 383     required: [requestId, operationType, status]
 384
 385     properties:
 386       requestId:
 387         type: string
 388         description: |
 389           A unique identifier assigned to the request.  Useful for tracing a request through logs.
 390       operationType:
 391         description: |
 392           Type of operation being reported on. ("install" or "uninstall")
 393         type: string
 394       status:
 395         description: |
 396           Status of the installation or uninstallation operation.  Possible values are "processing",
 397           "succeeded", and "failed"
 398         type: string
 399       error:
 400         description: |
 401           If status is "failed", this field will be present and contain additional information about the reason the operation failed.
 402         type: string
 403       links:
 404         description: |
 405          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.
 406         type: object
 407         properties:
 408           self:
 409             type: string
 410             description: |
 411               Link used to retrieve information about the service.
 412           uninstall:
 413             type: string
 414             description:
 415               Link used to trigger an "uninstall" operation for the service.  (Use the DELETE method.)
 416
 417   DCAEErrorResponse:
 418     description: |
 419       Object reporting an error.
 420     type:
 421       object
 422     required: [status]
 423
 424     properties:
 425       status:
 426         description: HTTP status code for the response
 427         type: integer
 428
 429       message:
 430         description: Human-readable description of the reason for the error
 431         type: string
 432
 433   DCAEDeploymentsListResponse:
 434     description: |
 435       Object providing a list of deployments
 436     type: object
 437     required: [requestId, deployments]
 438
 439     properties:
 440       requestId:
 441         type: string
 442         description: |
 443           Unique identifier for the request
 444       deployments:
 445         type: array
 446         items:
 447           type: object
 448           properties:
 449             href:
 450               type: string
 451               description: |
 452                   URL for the service deployment
 453
 454   DCAEPolicyBody:
 455     description: policy_body - the whole object received from policy-engine
 456     type: object
 457     required:
 458       - policyName
 459       - policyVersion
 460       - config
 461     properties:
 462       policyName:
 463         description: unique policy name that contains the version and extension
 464         type: string
 465       policyVersion:
 466         description: stringified int that is autoincremented by policy-engine
 467         type: string
 468       config:
 469         description: the policy-config - the config data provided by policy owner
 470         type: object
 471
 472   DCAEPolicy:
 473     description: policy object
 474     type: object
 475     required:
 476       - policy_id
 477       - policy_body
 478     properties:
 479       policy_id:
 480         description: unique identifier of policy regardless of its version
 481         type: string
 482       policy_body:
 483         $ref: "#/definitions/DCAEPolicyBody"
 484
 485   DCAEPolicyRequest:
 486     description: request to update policies on DCAE components.
 487     type: object
 488     required:
 489       - latest_policies
 490
 491     properties:
 492       latest_policies:
 493         description: "dictionary of (policy_id -> Policy object).  In example: replace additionalProp1,2,3 with policy_id1,2,3 values"
 494         type: object
 495         additionalProperties:
 496           $ref: "#/definitions/DCAEPolicy"