Merge "docs: Add (static) actions API to api-ref."

api-ref/source/v1/actions.inc

@@ -0,0 +1,129 @@
+.. -*- rst -*-
+
+==========================
+Actions and Static Actions
+==========================
+
+A Murano action is a type of MuranoPL method. The differences between a regular
+MuranoPL method are:
+
+* Action is executed on deployed objects.
+* Action execution is initiated by API request: you do not have to call the
+  method manually.
+
+Thus, Murano actions allow performing any operations on objects, like:
+
+* Getting information from the VM, like a config that is generated during the
+  deployment
+* VM rebooting
+* Scaling
+
+A list of available actions is formed during the environment deployment.
+Following deployment completion, you can call the action asynchronously. Murano
+engine generates a task for every action thereby allowing the action status to
+be tracked.
+
+Execute action
+==============
+
+.. rest_method::  POST /environments/{environment_id}/actions/{action_id}
+
+Execute action on deployed environment.
+
+Request Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - environment_id: env_id_url
+   - action_id: action_id_url
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - task_id: task_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/execute-action-response.json
+   :language: javascript
+
+Get Action Result
+=================
+
+.. rest_method::  GET /environments/{environment_id}/actions/{task_id}
+
+Retrieve action result for action executed on deployed environment.
+
+Request Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - environment_id: env_id_url
+   - task_id: task_id_url
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Execute static action
+=====================
+
+.. rest_method::  POST /actions
+
+Execute static action.
+
+Static methods can be called if they are exposed by specifying Scope: Public
+in the MuranoPL object and the result of its execution will be returned.
+
+Request Example
+---------------
+
+.. literalinclude:: samples/static-action-request.json
+   :language: javascript
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Response Example
+----------------
+
+.. literalinclude:: samples/static-action-response.json
+   :language: javascript

api-ref/source/v1/index.rst

@@ -6,6 +6,7 @@ OpenStack Application Catalog API v1
 
 .. rest_expand_all::
 
+.. include:: actions.inc
 .. include:: categories.inc
 .. include:: deployments.inc
 .. include:: environments.inc

api-ref/source/v1/parameters.yaml

@@ -17,6 +17,12 @@ abandon:
   required: false
   default: false
   type: boolean
+action_id_url:
+  description: |
+    The UUID of the action to be executed on the deployed environment.
+  in: path
+  required: true
+  type: string
 category_id_url:
   description: |
     The UUID of the category.
@@ -61,6 +67,13 @@ session_id_url:
   in: path
   required: true
   type: string
+task_id_url:
+  description: |
+    The UUID of the task associated with an action executed on a deployed
+    environment.
+  in: path
+  required: true
+  type: string
 template_id_url:
   description: |
     The UUID of the environment template.
@@ -504,6 +517,13 @@ tags:
   in: body
   required: true
   type: array
+task_id:
+  description: |
+    The UUID of the task associated with an action executed on a deployed
+    environment.
+  in: body
+  required: true
+  type: string
 template_description:
   description: |
     The enviroment template description.

api-ref/source/v1/samples/execute-action-response.json

@@ -0,0 +1,3 @@
+{
+	"task_id": "9e60318629ef47378b583825e7d282b7"
+}

api-ref/source/v1/samples/static-action-request.json

@@ -0,0 +1,5 @@
+{
+  "className": "ns.Bar",
+  "methodName": "staticAction",
+  "parameters": {"myName": "John"}
+}

api-ref/source/v1/samples/static-action-response.json

@@ -0,0 +1 @@
+"Hello, John"