From fa39e4b1fd06b9c673575419a91b64c98c41ffb1 Mon Sep 17 00:00:00 2001 From: tengqm Date: Thu, 18 Aug 2016 05:01:01 -0400 Subject: [PATCH] api-ref doc for stack (1) This patch, as a first step, fixes inaccuracies/bugs in api-ref documentation for stacks. The major changes in this patch include: - Added missing 'location' and 'X-OpenStack-Request-Id' parameters which both appear in some response headers. - Deleted some descriptions about parameters that are never referenced in any APIs. - Added missing 'deletion_time' parameter. - Added missing 'environment_files' parameter. - Added missing sample JSON file for stack-create-response.json. - Fixed errors in stack-preview-response.json. - Added tabular description of response codes. - Added a status.yaml file for response code description (shared). Change-Id: I826ed899f925812df9b44144469700453789e087 --- api-ref/source/v1/parameters.yaml | 486 ++++-------------- .../v1/samples/stack-preview-response.json | 5 +- api-ref/source/v1/stacks.inc | 99 ++-- api-ref/source/v1/status.yaml | 55 ++ 4 files changed, 238 insertions(+), 407 deletions(-) create mode 100644 api-ref/source/v1/status.yaml diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 052c11e589..377a5c73e9 100644 --- a/api-ref/source/v1/parameters.yaml +++ b/api-ref/source/v1/parameters.yaml @@ -1,4 +1,18 @@ # variables in header +location: + type: string + in: header + required: True + description: | + For asynchronous resource operations, the ``location`` header contains a + URI that can be checked to track resource status changes. + +request_id: + type: UUID + in: header + description: | + A unique ID for tracking service request. The request ID associated + with the request by default appears in the service logs. # variables in path config_id_url: @@ -45,13 +59,13 @@ snapshot_id: in: path required: false type: string -stack_id: +stack_id_url: description: | The UUID of the stack. in: path required: false type: string -stack_name: +stack_name_url: description: | The name of a stack. in: path @@ -66,9 +80,9 @@ template_version: tenant_id: description: | The UUID of the tenant. A tenant is also known as - an account or project. + a project. in: path - required: false + required: True type: string type_name: description: | @@ -355,8 +369,7 @@ ParameterGroups: type: array Parameters: description: | - Key and value pairs that contain template - parameters. + Key and value pairs that contain template parameters. in: body required: true type: object @@ -474,100 +487,8 @@ created_at: type: string creation_time: description: | - The date and time when the stack 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. - in: body - required: true - type: string -creation_time_1: - description: | - The date and time when the software 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. - in: body - required: true - type: string -creation_time_2: - 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. - in: body - required: true - type: string -creation_time_3: - description: | - The date and time when the snapshot 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. - in: body - required: true - type: string -creation_time_4: - description: | - The date and time when the software was created. - - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2016-03-30T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. - in: body - required: true - type: string -creation_time_5: - description: | - The date and time when the stack was created. - - The date and time stamp format is `ISO 8601 - `_: + The date and time when the resource was created. The date and time stamp + format is `ISO 8601 `_: :: @@ -604,6 +525,21 @@ deleted_at: in: body required: true type: string +deletion_time: + description: | + The date and time when the resource was (soft-) 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: body + required: true + type: string deployment_action: description: | The stack action that triggers this deployment resource. @@ -672,73 +608,18 @@ deployment_updated_time: type: string description: description: | - The description of the stack resource. - in: body - required: true - type: string -description_1: - description: | - The description of the resource attribute. - in: body - required: true - type: string -description_2: - description: | - The description of a stack output. - in: body - required: true - type: string -description_3: - description: | - The description of the active stack. - in: body - required: true - type: string -description_4: - description: | - A description of the stack. - in: body - required: true - type: string -description_5: - description: | - The description of the stack. - in: body - required: true - type: string -description_6: - description: | - The description of the stack template. + The description of the resource. in: body required: true type: string disable_rollback: description: | - Enables or disables deletion of all stack - resources when stack creation fails. Set to ``true`` to keep all - resources when stack creation fails. Set to ``false`` to delete - all resources when stack creation fails. Default is ``true``. + Enables or disables deletion of all stack resources when stack creation + fails. Set to ``true`` to keep all resources when stack creation fails. + Set to ``false`` to delete all resources when stack creation fails. in: body required: false - type: boolean -disable_rollback_1: - description: | - Enables or disables deletion of all previously- - created stack resources when stack creation fails. Set to ``true`` - to keep all previously-created stack resources when stack creation - fails. Set to ``false`` to delete all previously-created stack - resources when stack creation fails. Default is ``true``. - in: body - required: false - type: boolean -disable_rollback_2: - description: | - Enables or disables stack rollback when stack - creation fails. Set to ``true`` to rollback the stack when stack - creation fails. Set to ``false`` to disable stack rollback when - stack creation fails. Default is ``true``. - in: body - required: true + default: True type: boolean engine_id: description: | @@ -752,6 +633,12 @@ environment: in: body required: false type: object +environment_files: + description: | + An ordered list of names for environment files found in the ``files`` dict. + in: body + required: false + type: object files: description: | Supplies the contents of files referenced in the template or the @@ -859,12 +746,6 @@ id_3: in: body required: true type: string -id_5: - description: | - The UUID of the stack. - in: body - required: true - type: string input_values: description: | A dict comprises of input data as key-value pairs. @@ -886,17 +767,10 @@ inputs_1: type: array links: description: | - A list of URLs for the stack. Each URL is a JSON - object with an ``href`` key indicating the URL and a ``rel`` key - indicating its relationship to the stack in question. There may be - multiple links returned. The ``self`` relationship identifies the - URL of the stack itself. - in: body - required: true - type: array -links_1: - description: | - A list of stack links. + A list of URLs for the stack. Each URL is a JSON object with an ``href`` + key indicating the URL and a ``rel`` key indicating its relationship to + the stack in question. There may be multiple links returned. The ``self`` + relationship identifies the URL of the stack itself. in: body required: true type: array @@ -975,12 +849,6 @@ outputs_1: in: body required: true type: array -outputs_2: - description: | - A list of stack outputs. - in: body - required: true - type: array outputs_3: description: | Key and value pairs that contain output data. @@ -1064,72 +932,9 @@ parameters: in: body required: false type: object -parameters_1: - description: | - Key and value pairs that contain stack - parameters. - in: body - required: true - type: object -parameters_2: - description: | - Key and value pairs that contain template - parameters. - in: body - required: true - type: object -parameters_3: - description: "Supplies updated arguments for parameters that are defined in the\n\ - stack template.\n\nThe value is a JSON object, where each key is the name of a\n\ - parameter defined in the template and the associated value is the\nargument to\ - \ use for that parameter when instantiating the template.\nThe following code\ - \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\ - \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\ - \ json\n\n { ...\n \"parameters\": {\n \ - \ \"a\": \"Value\",\n \"b\": \"3\"\n \ - \ }\n ... }\n \n\ - \nWhile the service accepts JSON numbers for parameters with the type\n``number``\ - \ and JSON objects for parameters with the type ``json``,\nall parameter values\ - \ are converted to their string representation\nfor storage in the created Stack.\ - \ Clients are encouraged to send\nall parameter values using their string representation\ - \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\ - \nYou must specify a value for each template parameter that does not\nhave a default\ - \ value. However, this parameter cannot contain JSON\nproperties with names that\ - \ do not match a parameter that is defined\nin the template.\n" - in: body - required: false - type: object -parameters_4: - description: "This parameter supplies updated arguments for parameters defined in\n\ - the stack template.\n\nThe value is a JSON object, where each key is the name\ - \ of a\nparameter defined in the template and the associated value is the\nargument\ - \ to use for that parameter when instantiating the template.\nThe following code\ - \ shows the general structure of this parameter.\nIn the example, ``a`` and ``b``\ - \ are the names of two parameters\ndefined in the template.\n\n.. code-block::\ - \ json\n\n { ...\n \"parameters\": {\n \ - \ \"a\": \"Value\",\n \"b\": \"3\"\n \ - \ }\n ... }\n \n\nWhile\ - \ the service accepts JSON numbers for parameters with the type\n``number`` and\ - \ JSON objects for parameters with the type ``json``,\nall parameter values are\ - \ converted to their string representation\nfor storage in the created Stack.\ - \ Clients are encouraged to send\nall parameter values using their string representation\ - \ for\nconsistency between requests and responses from the Orchestration\nservice.\n\ - \nYou must specify a value for each template parameter that does not\nhave a default\ - \ value. However, this parameter cannot contain JSON\nproperties with names that\ - \ do not match a parameter that is defined\nin the template.\n" - in: body - required: false - type: object parent: description: | - The stack ID of the parent stack, if this is a - nested stack. - in: body - required: true - type: string -parent_1: - description: | - The parent of the stack. + The stack ID of the parent stack, if this is a nested stack. in: body required: true type: string @@ -1215,12 +1020,6 @@ resources: in: body required: true type: array -resources_1: - description: | - List of stack resources. - in: body - required: true - type: array resources_2: description: | The snapshot resources. @@ -1297,45 +1096,52 @@ stack: in: body required: true type: object -stack_name_1: +stack_id: description: | - A name for the new stack. The value must be - unique within a project. The name must start with an ASCII letter - and can contain ASCII letters, digits, underscores, periods, and - hyphens. Specifically, the name must match the - ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete - or abandon a stack, its name will not become available for reuse - until the deletion completes successfully. + The UUID of the stack. in: body required: true type: string -stack_name_2: +stack_name: description: | - A name for the new stack. This value must be - unique within a project. The name must start with an ASCII letter - and can contain ASCII letters, digits, underscores, periods, and - hyphens. Specifically, the name must match the - ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. When you delete - or abandon a stack, its name will not become available for reuse - until the deletion completes successfully. + A name for the stack. The value must be unique within a project. + The name must start with an ASCII letter and can contain ASCII letters, + digits, underscores, periods, and hyphens. Specifically, the name must + match the ``^[a-zA-Z][a-zA-Z0-9_.-]*$`` regular expression. + + When you delete or abandon a stack, its name will not become available + for reuse until the deletion completes successfully. in: body required: true type: string -stack_name_3: +stack_outputs: description: | - The name of the active stack. + A list of stack outputs. in: body required: true - type: string + type: array stack_owner: description: | - Stack owner name. + The owner of the stack in: body required: true type: string -stack_owner_1: +stack_parameters: description: | - The owner of the stack. + A group of key-value pairs where each key contains either a user-provided + parameter name or a built-in parameter name (e.g. ``OS::project_id``). + in: body + required: true + type: object +stack_resources: + description: | + List of stack resources. + in: body + required: true + type: array +stack_stack_user_project_id: + description: | + The project UUID of the stack user. in: body required: true type: string @@ -1357,6 +1163,18 @@ stack_status_reason: in: body required: true type: string +stack_tags: + description: | + The stack tags. + in: body + required: true + type: string +stack_timeout_mins: + description: | + The timeout for stack creation in minutes. + in: body + required: true + type: integer stack_user_project_id: description: | Authentication project ID, which can also perform @@ -1364,12 +1182,6 @@ stack_user_project_id: in: body required: false type: string -stack_user_project_id_1: - description: | - The project UUID of the stack user. - in: body - required: true - type: string status: description: | The status of the heat engine. @@ -1410,72 +1222,34 @@ suspend: type: string tags: description: | - One or more simple string tags to associate with - the stack. To associate multiple tags with a stack, separate the - tags with commas. For example, ``tag1,tag2``. + One or more simple string tags to associate with the stack. To associate + multiple tags with a stack, separate the tags with commas. + For example, ``tag1,tag2``. in: body required: false type: string -tags_2: - description: | - The stack tags. - in: body - required: true - type: string template: description: | The stack template on which to perform the operation. - This parameter is always provided as a ``string`` in the JSON - request body. The content of the string is a JSON- or YAML- - formatted Orchestration template. For example: + This parameter is always provided as a ``string`` in the JSON request body. + The content of the string is a JSON- or YAML-formatted Orchestration + template. For example: .. code-block:: json "template": { "heat_template_version": "2013-05-23", - ...} + ... + } This parameter is required only when you omit the ``template_url`` parameter. If you specify both parameters, this value overrides the ``template_url`` parameter value. in: body - required: true - type: object -template_1: - description: | - Information about the template. - in: body - required: true - type: object -template_2: - description: | - The stack template on which to perform the operation. - - This parameter is always provided as a ``string`` in the JSON - request body. The content of the string is a JSON- or YAML- - formatted Orchestration template. For example: - - .. code-block:: json - - "template": { - "heat_template_version": "2013-05-23", - ...} - - This parameter is required only when you omit the ``template_url`` - parameter. If you specify both parameters, this value overrides the - ``template_url`` parameter value. - in: body - required: false + required: False type: object template_description: - description: | - A description of the template that defines the - stack. - in: body - required: true - type: string -template_description_1: description: | The description of the stack template. in: body @@ -1483,12 +1257,11 @@ template_description_1: type: string template_url: description: | - A URI to the location containing the stack - template on which to perform the operation. See the description - of the ``template`` parameter for information about the expected - template content located at the URI. This parameter is only - required when you omit the ``template`` parameter. If you specify - both parameters, this parameter is ignored. + A URI to the location containing the stack template on which to perform + the operation. See the description of the ``template`` parameter for + information about the expected template content located at the URI. + This parameter is only required when you omit the ``template`` parameter. + If you specify both parameters, this parameter is ignored. in: body required: false type: string @@ -1498,18 +1271,6 @@ timeout_mins: in: body required: false type: integer -timeout_mins_1: - description: | - Time-lines for stack creation. - in: body - required: true - type: integer -timeout_mins_2: - description: | - The timeout, in minutes. - in: body - required: true - type: string topic: description: | The topic of the heat engine. @@ -1551,10 +1312,8 @@ updated_at: type: string updated_time: description: | - The date and time when the stack resource was updated. - - The date and time stamp format is `ISO 8601 - `_: + The date and time when the object was updated. The date and time stamp + format is `ISO 8601 `_: :: @@ -1562,32 +1321,7 @@ updated_time: For example, ``2015-08-27T09:49:58-05:00``. - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. - - If the ``updated_at`` date and time stamp is not set, its value is - ``null``. - in: body - required: true - type: string -updated_time_1: - description: | - The date and time when the stack resource was updated. - - The date and time stamp format is `ISO 8601 - `_: - - :: - - CCYY-MM-DDThh:mm:ss±hh:mm - - For example, ``2016-03-30T09:49:58-05:00``. - - The ``±hh:mm`` value, if included, is the time zone as an offset - from UTC. - - If the ``updated_at`` date and time stamp is not set, its value is - ``null``. + The ``±hh:mm`` value, if included, is the time zone as an offset from UTC. in: body required: true type: string diff --git a/api-ref/source/v1/samples/stack-preview-response.json b/api-ref/source/v1/samples/stack-preview-response.json index a36f8cf5d2..9e8a096888 100644 --- a/api-ref/source/v1/samples/stack-preview-response.json +++ b/api-ref/source/v1/samples/stack-preview-response.json @@ -2,6 +2,7 @@ "stack": { "capabilities": [], "creation_time": "2015-01-31T15:12:36Z", + "deletion_time": null, "description": "HOT template for Nova Server resource.\n", "disable_rollback": true, "id": "None", @@ -12,6 +13,7 @@ } ], "notification_topics": [], + "outputs": [], "parameters": { "OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804", "OS::stack_id": "None", @@ -160,7 +162,8 @@ } ], "stack_name": "test_stack", - "stack_owner": "admin", + "stack_owner": null, + "tags": null, "template_description": "HOT template for Nova Server resource.\n", "timeout_mins": null, "updated_time": null diff --git a/api-ref/source/v1/stacks.inc b/api-ref/source/v1/stacks.inc index 8b6c01cf0f..b85228757d 100644 --- a/api-ref/source/v1/stacks.inc +++ b/api-ref/source/v1/stacks.inc @@ -11,23 +11,34 @@ Create stack Creates a stack. -Error response codes:201,500,409,401,400, +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 409 Request Parameters ------------------ .. rest_parameters:: parameters.yaml - - files: files - - disable_rollback: disable_rollback - - parameters: parameters - - tags: tags - - stack_name: stack_name - - environment: environment - - template_url: template_url - - template: template - - timeout_mins: timeout_mins - tenant_id: tenant_id + - disable_rollback: disable_rollback + - environment: environment + - files: files + - parameters: parameters + - stack_name: stack_name + - tags: tags + - template: template + - template_url: template_url + - timeout_mins: timeout_mins Request Example --------------- @@ -40,9 +51,17 @@ Response Parameters .. rest_parameters:: parameters.yaml + - location: location + - X-Openstack-Reqeuest-Id: request_id + - stack: stack - id: id - links: links - - stack: stack + +Response Example +---------------- + +.. literalinclude:: samples/stack-create-response.json + :language: javascript Preview stack @@ -52,20 +71,35 @@ Preview stack Previews a stack. -Normal response codes: 200 -Error response codes:500,409,401,400, +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 409 + - 500 Request Parameters ------------------ .. rest_parameters:: parameters.yaml - - files: files - - stack_name: stack_name - - template_url: template_url - - template: template - - parameters: parameters - tenant_id: tenant_id + - disable_rollback: disable_rollback + - environment: environment + - files: files + - parameters: parameters + - stack_name: stack_name + - tags: tags + - template: template + - template_url: template_url + - timeout_mins: timeout_mins Request Example --------------- @@ -78,22 +112,27 @@ Response Parameters .. rest_parameters:: parameters.yaml - - parent: parent - - disable_rollback: disable_rollback - - description: description - - links: links - - stack_name: stack_name - - timeout_mins: timeout_mins - - creation_time: creation_time + - X-Openstack-Reqeuest-Id: request_id - capabilities: capabilities + - creation_time: creation_time + - deletion_time: deletion_time + - description: description + - disable_rollback: disable_rollback + - id: stack_id + - links: links - notification_topics: notification_topics - - updated_time: updated_time - - stack_owner: stack_owner - - stack: stack - - parameters: parameters - - id: id + - outputs: stack_outputs + - parameters: stack_parameters + - parent: parent - resources: resources + - stack: stack + - stack_name: stack_name + - stack_owner: stack_owner + - stack_user_project_id: stack_stack_user_project_id + - tags: stack_tags - template_description: template_description + - timeout_mins: timeout_mins + - updated_time: updated_time Response Example ---------------- diff --git a/api-ref/source/v1/status.yaml b/api-ref/source/v1/status.yaml new file mode 100644 index 0000000000..bf70c6a5bc --- /dev/null +++ b/api-ref/source/v1/status.yaml @@ -0,0 +1,55 @@ +################# +# Success Codes # +################# +200: + default: | + Request was successful. +201: + default: | + Resource was created and is ready to use. +202: + default: | + Request was accepted for processing, but the processing has not been + completed. A 'location' header is included in the response which contains + a link to check the progress of the request. +204: + default: | + The server has fulfilled the request by deleting the resource. +300: + default: | + There are multiple choices for resources. The request has to be more + specific to successfully retrieve one of these resources. + +################# +# Error Codes # +################# + +400: + default: | + Some content in the request was invalid. +401: + default: | + User must authenticate before making a request. +403: + default: | + Policy does not allow current user to do this operation. +404: + default: | + The requested resource could not be found. +405: + default: | + Method is not valid for this endpoint. +409: + default: | + This operation conflicted with another operation on this resource. + duplcate_zone: | + There is already a zone with this name. +500: + default: | + Something went wrong inside the service. This should not happen usually. + If it does happen, it means the server has experienced some serious + problems. +503: + default: | + Service is not available. This is mostly caused by service configuration + errors which prevents the service from successful start up.