diff options
author | 2019-05-14 17:45:22 +0000 | |
---|---|---|
committer | 2019-05-16 13:58:23 +0000 | |
commit | 1af30536774a0872b180f6c74a3e4ed487218747 (patch) | |
tree | bd09e30c08462cd1a032ca21ac6c5aac54ef1399 /docs/sections/apis/deployment-handler.rst | |
parent | b643761e44851acf519fa039e11c2f413e7a25aa (diff) |
Integration with Swagger
Correct doc8 errors
Add licence in RST
Add API table
Add swaggerv2doc when OK
Issue-ID: DCAEGEN2-1049
Change-Id: I7478b1c34625ce03ee4f1278a04a408f6f73718e
Signed-off-by: Eric Debeau <eric.debeau@orange.com>
Diffstat (limited to 'docs/sections/apis/deployment-handler.rst')
-rw-r--r-- | docs/sections/apis/deployment-handler.rst | 239 |
1 files changed, 39 insertions, 200 deletions
diff --git a/docs/sections/apis/deployment-handler.rst b/docs/sections/apis/deployment-handler.rst index 32373c9b..dc172a29 100644 --- a/docs/sections/apis/deployment-handler.rst +++ b/docs/sections/apis/deployment-handler.rst @@ -1,43 +1,37 @@ +.. 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. - - - - +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 +++++++++++ @@ -45,7 +39,6 @@ Description Uninstall the DCAE service and remove all associated data from the orchestrator. - Parameters ++++++++++ @@ -54,13 +47,11 @@ Parameters :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. - + deploymentId | path | Yes | string | | | Deployment identifier for the service to be uninstalled. Request +++++++ - Responses +++++++++ @@ -69,8 +60,6 @@ Responses Success: The dispatcher has initiated the uninstall operation. - - Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>` **Example:** @@ -90,8 +79,6 @@ Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>` Bad request: See the message in the response for details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -109,8 +96,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Problem on the server side. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -128,8 +113,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error reported to the dispatcher by a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -147,8 +130,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error communicating with a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -160,15 +141,9 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` "status": 1 } - - - - GET ``/dcae-deployments`` ------------------------- - - Description +++++++++++ @@ -176,7 +151,6 @@ Description List service deployments known to the orchestrator, optionally restricted to a single service type - Parameters ++++++++++ @@ -185,23 +159,19 @@ Parameters :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 - + 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.) - - +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>` @@ -227,8 +197,6 @@ Type: :ref:`DCAEDeploymentsListResponse <d_c51e57d9583f6119caf83dd017cf214c>` Problem on the server side. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -246,8 +214,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error reported to the dispatcher by a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -265,8 +231,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error communicating with a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -278,15 +242,9 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` "status": 1 } - - - - GET ``/dcae-deployments/{deploymentId}/operation/{operationId}`` ---------------------------------------------------------------- - - Description +++++++++++ @@ -294,7 +252,6 @@ Description Get status of a deployment operation - Parameters ++++++++++ @@ -303,14 +260,12 @@ Parameters :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 | | | - + deploymentId | path | Yes | string | | | + operationId | path | Yes | string | | | Request +++++++ - Responses +++++++++ @@ -319,7 +274,6 @@ Responses Status information retrieved successfully - Type: :ref:`DCAEOperationStatusResponse <d_f0103f05736b04468a4f85fe90da2e16>` **Example:** @@ -340,8 +294,8 @@ Type: :ref:`DCAEOperationStatusResponse <d_f0103f05736b04468a4f85fe90da2e16>` **404** ^^^^^^^ -The operation information does not exist (possibly because the service has been uninstalled and deleted). - +The operation information does not exist (possibly because the service has been +uninstalled and deleted). Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` @@ -360,8 +314,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Problem on the server side. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -379,8 +331,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error reported to the dispatcher by a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -398,8 +348,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error communicating with a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -411,15 +359,9 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` "status": 1 } - - - - PUT ``/dcae-deployments/{deploymentId}`` ---------------------------------------- - - Description +++++++++++ @@ -427,7 +369,6 @@ Description Request deployment of a DCAE service - Parameters ++++++++++ @@ -436,14 +377,11 @@ Parameters :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. - + deploymentId | path | Yes | string | | | Unique deployment identifier assigned by the API client. Request +++++++ - - .. _d_eea14e4929853a5aa415f44cd4868302: Body @@ -451,29 +389,20 @@ 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. - + 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. - - - +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 @@ -489,10 +418,8 @@ Responses ^^^^^^^ 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. - - + found the needed blueprint, created an instance of the topology in the + orchestrator, and started an installation workflow. Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>` @@ -513,8 +440,6 @@ Type: :ref:`DCAEDeploymentResponse <d_6157bd3de5c8c7de78f2ab86397667e0>` Bad request: See the message in the response for details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -529,9 +454,8 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **409** ^^^^^^^ -A service with the specified deployment Id already exists. Using PUT to update the service is not a supported operation. - - +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>` @@ -550,8 +474,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Bad request: The Content-Type header does not indicate that the content is 'application/json' - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -569,8 +491,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Problem on the server side. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -588,8 +508,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error reported to the dispatcher by a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -607,8 +525,6 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` Error communicating with a downstream system. See the message in the response for more details. - - Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` **Example:** @@ -621,23 +537,14 @@ Type: :ref:`DCAEErrorResponse <d_74f3f4f847dfb6bd181fcae06ad880b4>` } - - INFO ~~~~ - version and links - - - - GET ``/`` --------- - - Description +++++++++++ @@ -645,11 +552,9 @@ Description Returns version information and links to API operations - Request +++++++ - Responses +++++++++ @@ -658,7 +563,6 @@ Responses Success - .. _i_2e7b26d45eaa7203222963d454a86a88: **Response Schema:** @@ -674,15 +578,12 @@ Success 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" @@ -692,8 +593,6 @@ Links to API resources info | No | string | | | path for the server information endpoint - - **Example:** .. code-block:: javascript @@ -708,23 +607,15 @@ Links to API resources } - - POLICY ~~~~~~ - -policy update API consumed by policy-handler and debug API to find policies on components - - - - +policy update API consumed by policy-handler and debug API to find policies +on components GET ``/policy/components`` -------------------------- - - Description +++++++++++ @@ -732,11 +623,9 @@ Description debug API to find policies on components - Request +++++++ - Responses +++++++++ @@ -746,15 +635,9 @@ Responses deployment-handler found components with or without policies in cloudify - - - - POST ``/policy`` ---------------- - - Description +++++++++++ @@ -762,12 +645,9 @@ Description policy update API consumed by policy-handler - Request +++++++ - - .. _d_6ea6e6f48a0302e963a67833bbd0ff4a: Body @@ -787,42 +667,33 @@ request to update policies on DCAE components. 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 @@ -857,22 +728,18 @@ Responses **200** ^^^^^^^ -deployment-handler always responds with ok to /policy before processing the request - - +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" @@ -881,16 +748,10 @@ Request for deploying a DCAE service. 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. - - - +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: @@ -899,7 +760,6 @@ DCAEDeploymentResponse Model Structure Response body for a PUT or DELETE to /dcae-deployments/{deploymentId} - .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" @@ -909,15 +769,12 @@ Response body for a PUT or DELETE to /dcae-deployments/{deploymentId} 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" @@ -934,21 +791,18 @@ 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>` | | | + 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" @@ -956,7 +810,6 @@ Object providing a list of deployments href | No | string | | | URL for the service deployment - .. _d_74f3f4f847dfb6bd181fcae06ad880b4: DCAEErrorResponse Model Structure @@ -964,7 +817,6 @@ DCAEErrorResponse Model Structure Object reporting an error. - .. csv-table:: :delim: | :header: "Name", "Required", "Type", "Format", "Properties", "Description" @@ -978,8 +830,8 @@ Object reporting an error. DCAEOperationStatusResponse Model Structure ------------------------------------------- -Response body for a request for status of an installation or uninstallation operation. - +Response body for a request for status of an installation or uninstallation +operation. .. csv-table:: :delim: | @@ -996,14 +848,13 @@ Response body for a request for status of an installation or uninstallation oper 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. - +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: | @@ -1026,7 +877,7 @@ policy object :header: "Name", "Required", "Type", "Format", "Properties", "Description" :widths: 20, 10, 15, 15, 30, 25 - policy_body | Yes | :ref:`DCAEPolicyBody <d_7ffe00ee1aaae6811199d64ff3fea344>` | | | + policy_body | Yes | :ref:`DCAEPolicyBody <d_7ffe00ee1aaae6811199d64ff3fea344>` | | | policy_id | Yes | string | | | unique identifier of policy regardless of its version .. _d_7ffe00ee1aaae6811199d64ff3fea344: @@ -1049,11 +900,8 @@ policy_body - the whole object received from policy-engine **Config schema:** - the policy-config - the config data provided by policy owner - - DCAEPolicyRequest Model Structure --------------------------------- @@ -1071,35 +919,26 @@ request to update policies on DCAE components. 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"} |