api-ref - services/stack-outputs doc

This patch fixes inaccuracies/defects in the api-ref documentation for services and stack-outputs. Change-Id: I083607df0f5b72ee004e23d855df870a963c1578
6 years ago · 14a7304a62
9 changed files with 135 additions and 145 deletions
--- a/api-ref/source/v1/index.rst
+++ b/api-ref/source/v1/index.rst
@ -32,4 +32,4 @@ Orchestration Service API v1
 .. include:: stack-templates.inc
 .. include:: software-config.inc
 .. include:: resource-types.inc
-.. include:: service-status.inc
+.. include:: services.inc
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@ -42,7 +42,7 @@ event_id_url:
  in: path
  required: false
  type: string
-output_key_1:
+output_key_url:
  description: |
    The key of a stack output.
  in: path
@ -369,7 +369,7 @@ attributes:
  type: object
 binary:
  description: |
-    The name of the binary form of the heat engine.
+    The name of the binary executable of the heat engine.
  in: body
  required: true
  type: string
@ -461,19 +461,7 @@ config_name:
  type: string
 created_at:
  description: |
-    The date and time when the resource was created.
-
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC.
+    The date and time when the service engine was created.
  in: body
  required: true
  type: string
@ -501,19 +489,7 @@ data:
  type: object
 deleted_at:
  description: |
-    The date and time when the resource was deleted.
-
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC. In the previous example, the offset value is ``-05:00``.
+    The date and time when the service engine was deleted.
  in: body
  required: true
  type: string
@ -621,7 +597,20 @@ disable_rollback:
  type: boolean
 engine_id:
  description: |
-    The ID of engine service.
+    The UUID of the engine service.
+  in: body
+  required: true
+  type: string
+engine_record_id:
+  description: |
+    The UUID of the heat engine service record. Note that each service engine
+    may have multiple records in the service registry.
+  in: body
+  required: true
+  type: string
+engine_status:
+  description: |
+    The status of the heat engine.
  in: body
  required: true
  type: string
@ -740,25 +729,13 @@ HeatTemplateFormatVersion:
  type: string
 host:
  description: |
-    The host for the service.
+    The host on which the service engine is or was running.
  in: body
  required: true
  type: string
 hostname:
  description: |
-    The name of the host for the service.
-  in: body
-  required: true
-  type: string
-id:
-  description: |
-    The UUID of the heat engine.
-  in: body
-  required: true
-  type: string
-id_3:
-  description: |
-    The UUID of the snapshot.
+    The name of the host for the service engine.
  in: body
  required: true
  type: string
@ -827,12 +804,25 @@ options:
  in: body
  required: false
  type: string
-output_error:
+output:
  description: |
-    The error in a stack output.
+    An output record for the specified key.
+  in: body
+  required: true
+  type: object
+output_description:
+  description: |
+    A textual description of a stack output.
  in: body
  required: true
  type: string
+output_error:
+  description: |
+    The error in a stack output. This key only appears when an output has
+    problem in resolving its value.
+  in: body
+  required: false
+  type: string
 output_key:
  description: |
    The name of a stack output.
@ -1009,8 +999,8 @@ properties:
  type: object
 report_interval:
  description: |
-    The polling interval, in seconds. The API reports
-    events at this interval until heat engine creation completes.
+    The polling interval, in seconds. The API reports events at this interval
+    until heat engine creation completes.
  in: body
  required: true
  type: integer
@ -1134,12 +1124,24 @@ snapshot:
  in: body
  required: true
  type: object
+snapshot_id:
+  description: |
+    The UUID of the snapshot.
+  in: body
+  required: true
+  type: string
 snapshot_name:
  description: |
    The name of the snapshot.
  in: body
  required: true
  type: string
+snapshot_status:
+  description: |
+    The status of the snapshot.
+  in: body
+  required: true
+  type: string
 snapshots:
  description: |
    A list of snapshots and their properties.
@ -1305,18 +1307,6 @@ stacks:
  in: body
  required: true
  type: array
-status:
-  description: |
-    The status of the heat engine.
-  in: body
-  required: true
-  type: string
-status_4:
-  description: |
-    The status of the snapshot.
-  in: body
-  required: true
-  type: string
 status_reason:
  description: |
    Error description for the last status change,
@ -1428,7 +1418,7 @@ title:
  type: string
 topic:
  description: |
-    The topic of the heat engine.
+    The messaging topic of the heat engine.
  in: body
  required: true
  type: string
@ -1453,22 +1443,7 @@ update_show_nested:
  type: boolean
 updated_at:
  description: |
-    The date and time when the resource was updated.
-
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC. In the previous example, the offset value is ``-05:00``.
-
-    If the ``updated_at`` date and time stamp is not set, its value is
-    ``null``.
+    The date and time when the service engine was updated.
  in: body
  required: true
  type: string
--- a/api-ref/source/v1/samples/services-list-response.json
+++ b/api-ref/source/v1/samples/services-list-response.json
@ -1,30 +1,30 @@
 {
    "services": [
        {
-            "status": "up",
            "binary": "heat-engine",
-            "report_interval": 60,
-            "engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d",
            "created_at": "2015-02-03T05:55:59.000000",
+            "deleted_at": null,
+            "engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d",
+            "host": "engine-1",
            "hostname": "mrkanag",
-            "updated_at": "2015-02-03T05:57:59.000000",
+            "id": "e1908f44-42f9-483f-b778-bc814072c33d",
+            "report_interval": 60,
+            "status": "up",
            "topic": "engine",
-            "host": "engine-1",
-            "deleted_at": null,
-            "id": "e1908f44-42f9-483f-b778-bc814072c33d"
+            "updated_at": "2015-02-03T05:57:59.000000"
        },
        {
-            "status": "down",
            "binary": "heat-engine",
-            "report_interval": 60,
-            "engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306",
            "created_at": "2015-02-03T06:03:14.000000",
+            "deleted_at": null,
+            "engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306",
+            "host": "engine",
            "hostname": "mrkanag",
-            "updated_at": "2015-02-03T06:09:55.000000",
+            "id": "582b5657-6db7-48ad-8483-0096350faa21",
+            "report_interval": 60,
+            "status": "down",
            "topic": "engine",
-            "host": "engine",
-            "deleted_at": null,
-            "id": "582b5657-6db7-48ad-8483-0096350faa21"
+            "updated_at": "2015-02-03T06:09:55.000000"
        }
    ]
 }
--- a/api-ref/source/v1/samples/stack-output-show-response.json
+++ b/api-ref/source/v1/samples/stack-output-show-response.json
@ -3,6 +3,6 @@
        "output_key": "output_name",
        "output_value": "output_value",
        "description": "output description",
-        "output_error": null
+        "output_error": "error message"
    }
 }
--- a/api-ref/source/v1/samples/stack-outputs-list-response.json
+++ b/api-ref/source/v1/samples/stack-outputs-list-response.json
@ -2,9 +2,7 @@
    "outputs": [
        {
            "output_key": "output name",
-            "output_value": "output value",
            "description": "output description",
-            "output_error": null
        }
    ]
 }
--- a/api-ref/source/v1/service-status.inc
+++ b/api-ref/source/v1/service-status.inc
@ -4,9 +4,6 @@
 Manage service
 ==============

-
-
-
 Show orchestration engine status
 ================================

@ -17,53 +14,52 @@ Enables administrative users to view details for all orchestration engines.
 Orchestration engine details include engine id, binary, topic name, host, 
 report interval, last updated time, health status, and host name.

-Troubleshooting
+Response Codes
+--------------

- A ``503`` error code indicates that the heat engines are not
-  operational. Run the heat-manage service list command or contact
-  your cloud provider to determine why the heat engines are not
-  operational.
+.. rest_status_code:: success status.yaml

+   - 200

-Normal response codes: 200
-Error response codes:403,503,
+.. rest_status_code:: error status.yaml
+
+   - 403
+   - 503
+
+Troubleshooting

+- A ``503`` error code indicates that the heat engines are not operational.
+  Run the ``heat-manage service list`` command or contact your cloud provider
+  to determine why the heat engines are not operational.

-Request
-------
+Request Parameters
+------------------

 .. rest_parameters:: parameters.yaml

   - tenant_id: tenant_id

-
 Response Parameters
 -------------------

 .. rest_parameters:: parameters.yaml

-   - status: status
+   - X-Openstack-Request-Id: request_id
+   - services: services
   - binary: binary
-   - report_interval: report_interval
-   - engine_id: engine_id
   - created_at: created_at
+   - deleted_at: deleted_at
+   - engine_id: engine_id
+   - host: host
   - hostname: hostname
-   - updated_at: updated_at
+   - id: engine_record_id
+   - report_interval: report_interval
+   - status: engine_status
   - topic: topic
-   - host: host
-   - services: services
-   - deleted_at: deleted_at
-   - id: id
-
-
+   - updated_at: updated_at

 Response Example
 ----------------

 .. literalinclude:: samples/services-list-response.json
   :language: javascript
-
-
-
-
-
--- a/api-ref/source/v1/stack-outputs.inc
+++ b/api-ref/source/v1/stack-outputs.inc
@ -11,28 +11,37 @@ List outputs

 Lists outputs for a stack.

+Response Codes
+--------------

-Normal response codes: 200
-Error response codes:
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
+   - 500

 Request Parameters
 ------------------

 .. rest_parameters:: parameters.yaml

-   - stack_name: stack_name
   - tenant_id: tenant_id
-   - stack_id: stack_id
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url

 Response Parameters
 -------------------

 .. rest_parameters:: parameters.yaml

-   - output_value: output_value
-   - output_error: output_error
-   - description: description
+   - X-Openstack-Request-Id: request_id
+   - outputs: stack_outputs
   - output_key: output_key
+   - description: output_description

 Response Example
 ----------------
@ -48,31 +57,43 @@ Show output

 Shows details for a stack output.

-Normal response codes: 200
-Error response codes:
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 404
+   - 500

 Request Parameters
 ------------------

 .. rest_parameters:: parameters.yaml

-   - stack_name: stack_name
   - tenant_id: tenant_id
-   - stack_id: stack_id
-   - output_key: output_key
+   - stack_name: stack_name_url
+   - stack_id: stack_id_url
+   - output_key: output_key_url

 Response Parameters
 -------------------

 .. rest_parameters:: parameters.yaml

+   - X-Openstack-Reqeuest-Id: request_id
+   - output: output
+   - output_key: output_key
   - output_value: output_value
+   - description: output_description
   - output_error: output_error
-   - description: description
-   - output_key: output_key

 Response Example
 ----------------

-.. literalinclude:: samples/stack-show-output-response.json
+.. literalinclude:: samples/stack-output-show-response.json
   :language: javascript
--- a/api-ref/source/v1/stack-snapshots.inc
+++ b/api-ref/source/v1/stack-snapshots.inc
@ -35,12 +35,12 @@ Response Parameters

 .. rest_parameters:: parameters.yaml

-   - status: status
+   - status: snapshot_status
   - name: snapshot_name
   - status_reason: status_reason
   - creation_time: creation_time
   - data: data
-   - id: id
+   - id: snapshot_id

 Response Example
 ----------------
@ -75,7 +75,7 @@ Response Parameters

 .. rest_parameters:: parameters.yaml

-   - status: status
+   - status: snapshot_status
   - name: snapshot_name
   - status_reason: status_reason
   - creation_time: creation_time
@ -83,7 +83,7 @@ Response Parameters
   - template: template
   - project_id: project_id
   - data: data
-   - id: id
+   - id: snapshot_id
   - resources: resources

 Response Example
@ -116,13 +116,13 @@ Response Parameters

 .. rest_parameters:: parameters.yaml

-   - status: status
+   - status: snapshot_status
   - name: snapshot_name
   - status_reason: status_reason
   - creation_time: creation_time
   - snapshots: snapshots
   - data: data
-   - id: id
+   - id: snapshot_id

 Response Example
 ----------------
--- a/api-ref/source/v1/stacks.inc
+++ b/api-ref/source/v1/stacks.inc
@ -54,7 +54,7 @@ Response Parameters
   - location: location
   - X-Openstack-Reqeuest-Id: request_id
   - stack: stack
-   - id: id
+   - id: stack_id
   - links: links

 Response Example
@ -666,7 +666,7 @@ Response Parameters
   - location: location
   - X-Openstack-Reqeuest-Id: request_id
   - stack: stack
-   - id: id
+   - id: stack_id
   - links: links

 Response Example