blob: dc172a29dc69e6e1fb1c501eb1d130e608c96549 [file] [log] [blame]
.. This work is licensed under a
Creative Commons Attribution 4.0 International License.
deployment-handler API 3.0.3
============================
.. toctree::
:maxdepth: 3
.. csv-table::
:header: "API name", "Swagger JSON", "Swagger YAML"
:widths: 10,5,5
"deployment-handler", ":download:`link <deployment-handler-API.json>`", ":download:`link <deployment-handler-API.yaml>`"
Description
~~~~~~~~~~~
High-level API for deploying/undeploying composed DCAE services using
Cloudify Manager.
License
~~~~~~~
`Apache 2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_
DCAE-DEPLOYMENTS
~~~~~~~~~~~~~~~~
operations on dcae-deployments
DELETE ``/dcae-deployments/{deploymentId}``
-------------------------------------------
Description
+++++++++++
.. raw:: html
Uninstall the DCAE service and remove all associated data from the orchestrator.
Parameters
++++++++++
.. csv-table::
:delim: |
:header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 15, 10, 10, 10, 20, 30
deploymentId | path | Yes | string | | | Deployment identifier for the service to be uninstalled.
Request
+++++++
Responses
+++++++++
**202**
^^^^^^^
Success: The dispatcher has initiated the uninstall operation.
Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>`
**Example:**
.. code-block:: javascript
{
"links": {
"self": "somestring",
"status": "somestring"
},
"requestId": "somestring"
}
**400**
^^^^^^^
Bad request: See the message in the response for details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**500**
^^^^^^^
Problem on the server side. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**502**
^^^^^^^
Error reported to the dispatcher by a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**504**
^^^^^^^
Error communicating with a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
GET ``/dcae-deployments``
-------------------------
Description
+++++++++++
.. raw:: html
List service deployments known to the orchestrator, optionally restricted to a single service type
Parameters
++++++++++
.. csv-table::
:delim: |
:header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 15, 10, 10, 10, 20, 30
serviceTypeId | query | No | string | | | Service type identifier for the type whose deployments are to be listed
Request
+++++++
Responses
+++++++++
**200**
^^^^^^^
Success. (Note that if no matching deployments are found, the request is still
a success; the deployments array is empty in that case.)
Type: :ref:`DCAEDeploymentsListResponse <d_c51e57d9583f6119caf83dd017cf214c>`
**Example:**
.. code-block:: javascript
{
"deployments": [
{
"href": "somestring"
},
{
"href": "somestring"
}
],
"requestId": "somestring"
}
**500**
^^^^^^^
Problem on the server side. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**502**
^^^^^^^
Error reported to the dispatcher by a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**504**
^^^^^^^
Error communicating with a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
GET ``/dcae-deployments/{deploymentId}/operation/{operationId}``
----------------------------------------------------------------
Description
+++++++++++
.. raw:: html
Get status of a deployment operation
Parameters
++++++++++
.. csv-table::
:delim: |
:header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 15, 10, 10, 10, 20, 30
deploymentId | path | Yes | string | | |
operationId | path | Yes | string | | |
Request
+++++++
Responses
+++++++++
**200**
^^^^^^^
Status information retrieved successfully
Type: :ref:`DCAEOperationStatusResponse <d_f0103f05736b04468a4f85fe90da2e16>`
**Example:**
.. code-block:: javascript
{
"error": "somestring",
"links": {
"self": "somestring",
"uninstall": "somestring"
},
"operationType": "somestring",
"requestId": "somestring",
"status": "somestring"
}
**404**
^^^^^^^
The operation information does not exist (possibly because the service has been
uninstalled and deleted).
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**500**
^^^^^^^
Problem on the server side. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**502**
^^^^^^^
Error reported to the dispatcher by a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**504**
^^^^^^^
Error communicating with a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
PUT ``/dcae-deployments/{deploymentId}``
----------------------------------------
Description
+++++++++++
.. raw:: html
Request deployment of a DCAE service
Parameters
++++++++++
.. csv-table::
:delim: |
:header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 15, 10, 10, 10, 20, 30
deploymentId | path | Yes | string | | | Unique deployment identifier assigned by the API client.
Request
+++++++
.. _d_eea14e4929853a5aa415f44cd4868302:
Body
^^^^
Request for deploying a DCAE service.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
inputs | No | | | | 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.
serviceTypeId | Yes | string | | | The service type identifier (a unique ID assigned by DCAE inventory) for the service to be deployed.
.. _i_08ada55a389e24cd45beef83306fd08e:
**Inputs schema:**
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.
.. code-block:: javascript
{
"inputs": {},
"serviceTypeId": "somestring"
}
Responses
+++++++++
**202**
^^^^^^^
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.
Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>`
**Example:**
.. code-block:: javascript
{
"links": {
"self": "somestring",
"status": "somestring"
},
"requestId": "somestring"
}
**400**
^^^^^^^
Bad request: See the message in the response for details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**409**
^^^^^^^
A service with the specified deployment Id already exists. Using PUT to update
the service is not a supported operation.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**415**
^^^^^^^
Bad request: The Content-Type header does not indicate that the content is
'application/json'
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**500**
^^^^^^^
Problem on the server side. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**502**
^^^^^^^
Error reported to the dispatcher by a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
**504**
^^^^^^^
Error communicating with a downstream system. See the message
in the response for more details.
Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>`
**Example:**
.. code-block:: javascript
{
"message": "somestring",
"status": 1
}
INFO
~~~~
version and links
GET ``/``
---------
Description
+++++++++++
.. raw:: html
Returns version information and links to API operations
Request
+++++++
Responses
+++++++++
**200**
^^^^^^^
Success
.. _i_2e7b26d45eaa7203222963d454a86a88:
**Response Schema:**
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
apiVersion | No | string | | | version of API supported by this server
links | No | :ref:`links <i_bcea41e897f5de95cd50fa873acb5f65>` | | | Links to API resources
serverVersion | No | string | | | version of software running on this server
.. _i_bcea41e897f5de95cd50fa873acb5f65:
**Links schema:**
Links to API resources
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
events | No | string | | | path for the events endpoint
info | No | string | | | path for the server information endpoint
**Example:**
.. code-block:: javascript
{
"apiVersion": "somestring",
"links": {
"events": "somestring",
"info": "somestring"
},
"serverVersion": "somestring"
}
POLICY
~~~~~~
policy update API consumed by policy-handler and debug API to find policies
on components
GET ``/policy/components``
--------------------------
Description
+++++++++++
.. raw:: html
debug API to find policies on components
Request
+++++++
Responses
+++++++++
**200**
^^^^^^^
deployment-handler found components with or without policies in cloudify
POST ``/policy``
----------------
Description
+++++++++++
.. raw:: html
policy update API consumed by policy-handler
Request
+++++++
.. _d_6ea6e6f48a0302e963a67833bbd0ff4a:
Body
^^^^
request to update policies on DCAE components.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
catch_up | Yes | boolean | | | flag to indicate whether the request contains all the policies in PDP or not
errored_policies | No | | | | whether policy-engine returned an error on the policy.
errored_scopes | No | array of string | | | on cartchup - list of policy scope_prefix values on wchich the policy-engine experienced an error other than not-found data.
latest_policies | Yes | | | | dictionary of (policy_id -> DCAEPolicy object).
removed_policies | Yes | | | | whether policy was removed from policy-engine.
scope_prefixes | No | array of string | | | on catchup - list of all scope_prefixes used by the policy-handler to retrieve the policies from policy-engine.
.. _i_0e88fa72c5312eaae3990753181ce5fe:
**Errored_policies schema:**
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
Map of {"key":"boolean"}
.. _i_cbc40bad95bddbd536eeab0a92f483af:
**Latest_policies schema:**
dictionary of (policy_id -> DCAEPolicy object).
In example: replace additionalProp1,2,3 with policy_id1,2,3 values
Map of {"key":":ref:`DCAEPolicy <d_1e3e880a733b457b648bd8c99e6c859c>`"}
.. _i_0ce52a29e44aa0cc7929fe7b555551bc:
**Removed_policies schema:**
whether policy was removed from policy-engine.
dictionary of (policy_id -> true).
In example: replace additionalProp1,2,3 with policy_id1,2,3 values
Map of {"key":"boolean"}
.. code-block:: javascript
{
"catch_up": true,
"errored_policies": {},
"errored_scopes": [
"somestring",
"somestring"
],
"latest_policies": {
"DCAEPolicy": {
"policy_body": {
"config": {},
"policyName": "somestring",
"policyVersion": "somestring"
},
"policy_id": "somestring"
}
},
"removed_policies": {},
"scope_prefixes": [
"somestring",
"somestring"
]
}
Responses
+++++++++
**200**
^^^^^^^
deployment-handler always responds with ok to /policy before processing
the request
Data Structures
~~~~~~~~~~~~~~~
DCAEDeploymentRequest Model Structure
-------------------------------------
Request for deploying a DCAE service.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
inputs | No | | | | Object containing inputs needed by the service blueprint to create an instance of the service.
serviceTypeId | Yes | string | | | The service type identifier (a unique ID assigned by DCAE inventory) for the service to be deployed.
**Inputs schema:**
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.
.. _d_6157bd3de5c8c7de78f2ab86397667e0:
DCAEDeploymentResponse Model Structure
--------------------------------------
Response body for a PUT or DELETE to /dcae-deployments/{deploymentId}
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
links | Yes | :ref:`links <i_4a894329f99280d2268e250444b59376>` | | | Links that the API client can access.
requestId | Yes | string | | | Unique identifier for the request
.. _i_4a894329f99280d2268e250444b59376:
**Links schema:**
Links that the API client can access.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
self | No | string | | | Link used to retrieve information about the service being deployed
status | No | string | | | Link used to retrieve information about the status of the installation workflow
.. _d_c51e57d9583f6119caf83dd017cf214c:
DCAEDeploymentsListResponse Model Structure
-------------------------------------------
Object providing a list of deployments
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
deployments | Yes | array of :ref:`deployments <i_98a80d81e7d1973d54db7713913d37e8>` | | |
requestId | Yes | string | | | Unique identifier for the request
.. _i_98a80d81e7d1973d54db7713913d37e8:
**Deployments schema:**
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
href | No | string | | | URL for the service deployment
.. _d_74f3f4f847dfb6bd181fcae06ad880b4:
DCAEErrorResponse Model Structure
---------------------------------
Object reporting an error.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
message | No | string | | | Human-readable description of the reason for the error
status | Yes | integer | | | HTTP status code for the response
.. _d_f0103f05736b04468a4f85fe90da2e16:
DCAEOperationStatusResponse Model Structure
-------------------------------------------
Response body for a request for status of an installation or uninstallation
operation.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
error | No | string | | | If status is 'failed', this field will be present and contain additional information about the reason the operation failed.
links | No | :ref:`links <i_2feace8c1d3584ec637edc0eb1b92699>` | | | 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.
operationType | Yes | string | | | Type of operation being reported on. ('install' or 'uninstall')
requestId | Yes | string | | | A unique identifier assigned to the request. Useful for tracing a request through logs.
status | Yes | string | | | Status of the installation or uninstallation operation. Possible values are 'processing',
.. _i_2feace8c1d3584ec637edc0eb1b92699:
**Links schema:**
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.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
self | No | string | | | Link used to retrieve information about the service.
uninstall | No | string | | | Link used to trigger an 'uninstall' operation for the service. (Use the DELETE method.)
.. _d_1e3e880a733b457b648bd8c99e6c859c:
DCAEPolicy Model Structure
--------------------------
policy object
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
policy_body | Yes | :ref:`DCAEPolicyBody <d_7ffe00ee1aaae6811199d64ff3fea344>` | | |
policy_id | Yes | string | | | unique identifier of policy regardless of its version
.. _d_7ffe00ee1aaae6811199d64ff3fea344:
DCAEPolicyBody Model Structure
------------------------------
policy_body - the whole object received from policy-engine
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
config | Yes | :ref:`config <i_ba9593ef6832fb8401f266e173acaa5c>` | | | the policy-config - the config data provided by policy owner
policyName | Yes | string | | | unique policy name that contains the version and extension
policyVersion | Yes | string | | | stringified int that is autoincremented by policy-engine
.. _i_ba9593ef6832fb8401f266e173acaa5c:
**Config schema:**
the policy-config - the config data provided by policy owner
DCAEPolicyRequest Model Structure
---------------------------------
request to update policies on DCAE components.
.. csv-table::
:delim: |
:header: "Name", "Required", "Type", "Format", "Properties", "Description"
:widths: 20, 10, 15, 15, 30, 25
catch_up | Yes | boolean | | | flag to indicate whether the request contains all the policies in PDP or not
errored_policies | No | | | | whether policy-engine returned an error on the policy.
errored_scopes | No | array of string | | | on cartchup - list of policy scope_prefix values on wchich the policy-engine experienced an error other than not-found data.
latest_policies | Yes | | | | dictionary of (policy_id -> DCAEPolicy object).
removed_policies | Yes | | | | whether policy was removed from policy-engine.
scope_prefixes | No | array of string | | | on catchup - list of all scope_prefixes used by the policy-handler to retrieve the policies from policy-engine.
**Errored_policies schema:**
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
Map of {"key":"boolean"}
**Latest_policies schema:**
dictionary of (policy_id -> DCAEPolicy object).
In example: replace additionalProp1,2,3 with policy_id1,2,3 values
Map of {"key":":ref:`DCAEPolicy <d_1e3e880a733b457b648bd8c99e6c859c>`"}
**Removed_policies schema:**
whether policy was removed from policy-engine.
dictionary of (policy_id -> true).
In example: replace additionalProp1,2,3 with policy_id1,2,3 values
Map of {"key":"boolean"}