openstack/heat
Code Issues Proposed changes

api-ref - services/stack-outputs doc

Browse Source 
This patch fixes inaccuracies/defects in the api-ref documentation for
services and stack-outputs.

Change-Id: I083607df0f5b72ee004e23d855df870a963c1578
This commit is contained in:
tengqm 2016-08-19 05:59:07 -04:00 committed by Qiming Teng
parent 5a43527d8e
commit 14a7304a62
9 changed files with 142 additions and 152 deletions

2
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

127
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,11 +804,24 @@ 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: |
@ -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

32
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",
"hostname": "mrkanag",
"updated_at": "2015-02-03T05:57:59.000000",
"topic": "engine",
"host": "engine-1",
"deleted_at": null,
"id": "e1908f44-42f9-483f-b778-bc814072c33d"
"engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d",
"host": "engine-1",
"hostname": "mrkanag",
"id": "e1908f44-42f9-483f-b778-bc814072c33d",
"report_interval": 60,
"status": "up",
"topic": "engine",
"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",
"hostname": "mrkanag",
"updated_at": "2015-02-03T06:09:55.000000",
"topic": "engine",
"host": "engine",
"deleted_at": null,
"id": "582b5657-6db7-48ad-8483-0096350faa21"
"engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306",
"host": "engine",
"hostname": "mrkanag",
"id": "582b5657-6db7-48ad-8483-0096350faa21",
"report_interval": 60,
"status": "down",
"topic": "engine",
"updated_at": "2015-02-03T06:09:55.000000"
}
]
}

2
api-ref/source/v1/samples/stack-show-output-response.json → 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"
}
}

2
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
}
]
}

60
api-ref/source/v1/service-status.inc → api-ref/source/v1/services.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.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. 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.
- 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.
Normal response codes: 200
Error response codes:403,503,
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- binary: binary
- report_interval: report_interval
- engine_id: engine_id
- created_at: created_at
- hostname: hostname
- updated_at: updated_at
- topic: topic
- host: host
- X-Openstack-Request-Id: request_id
- services: services
- binary: binary
- created_at: created_at
- deleted_at: deleted_at
- id: id
- engine_id: engine_id
- host: host
- hostname: hostname
- id: engine_record_id
- report_interval: report_interval
- status: engine_status
- topic: topic
- updated_at: updated_at
Response Example
----------------
.. literalinclude:: samples/services-list-response.json
:language: javascript

53
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
- output_value: output_value
- output_error: output_error
- description: description
- X-Openstack-Reqeuest-Id: request_id
- output: output
- output_key: output_key
- output_value: output_value
- description: output_description
- output_error: output_error
Response Example
----------------
.. literalinclude:: samples/stack-show-output-response.json
.. literalinclude:: samples/stack-output-show-response.json
:language: javascript

12
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
----------------

4
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