From 14a7304a62e50e9f2918b00c8fa20426c22d67c5 Mon Sep 17 00:00:00 2001 From: tengqm Date: Fri, 19 Aug 2016 05:59:07 -0400 Subject: [PATCH] api-ref - services/stack-outputs doc This patch fixes inaccuracies/defects in the api-ref documentation for services and stack-outputs. Change-Id: I083607df0f5b72ee004e23d855df870a963c1578 --- api-ref/source/v1/index.rst | 2 +- api-ref/source/v1/parameters.yaml | 127 +++++++----------- .../v1/samples/services-list-response.json | 32 ++--- ...e.json => stack-output-show-response.json} | 2 +- .../samples/stack-outputs-list-response.json | 2 - .../v1/{service-status.inc => services.inc} | 60 ++++----- api-ref/source/v1/stack-outputs.inc | 53 +++++--- api-ref/source/v1/stack-snapshots.inc | 12 +- api-ref/source/v1/stacks.inc | 4 +- 9 files changed, 142 insertions(+), 152 deletions(-) rename api-ref/source/v1/samples/{stack-show-output-response.json => stack-output-show-response.json} (78%) rename api-ref/source/v1/{service-status.inc => services.inc} (65%) diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst index 9bb4d16bfa..1458784d42 100644 --- 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 diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 380edbc23e..96cc686d0b 100644 --- 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 - `_: - - :: - - 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 - `_: - - :: - - 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 - `_: - - :: - - 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 diff --git a/api-ref/source/v1/samples/services-list-response.json b/api-ref/source/v1/samples/services-list-response.json index b49be73147..f53161b6e2 100644 --- 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", - "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" } ] } diff --git a/api-ref/source/v1/samples/stack-show-output-response.json b/api-ref/source/v1/samples/stack-output-show-response.json similarity index 78% rename from api-ref/source/v1/samples/stack-show-output-response.json rename to api-ref/source/v1/samples/stack-output-show-response.json index 356eb60b6e..8a6841aee9 100644 --- a/api-ref/source/v1/samples/stack-show-output-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" } } diff --git a/api-ref/source/v1/samples/stack-outputs-list-response.json b/api-ref/source/v1/samples/stack-outputs-list-response.json index 8cb61499f1..ce9fabebbe 100644 --- 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 } ] } diff --git a/api-ref/source/v1/service-status.inc b/api-ref/source/v1/services.inc similarity index 65% rename from api-ref/source/v1/service-status.inc rename to api-ref/source/v1/services.inc index 6adb4e4392..67b344cd5b 100644 --- a/api-ref/source/v1/service-status.inc +++ b/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 - - - - - diff --git a/api-ref/source/v1/stack-outputs.inc b/api-ref/source/v1/stack-outputs.inc index daf43f4a6c..c0d60702d0 100644 --- 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 - - 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 diff --git a/api-ref/source/v1/stack-snapshots.inc b/api-ref/source/v1/stack-snapshots.inc index 4c14336545..85e6e0cc72 100644 --- 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 ---------------- diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc index 65ffe49dc9..415883e4d5 100644 --- 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