openstack/heat
Code Issues Proposed changes

api-ref - build/resource-type/versions

Browse Source 
This patch fixes the format and content of the api-ref documentation for
the build-info, resource-type-{list|template|schema}, versions APIs.
Major changes include:
- use status code table to show response codes
- add missing response parameters such as request id
- fixed cases where the response format was not clearly/correctly
  documented.

Change-Id: Id7ac58ff19d3f7a0feb4d872efa7b46c01fa8f4b
This commit is contained in:
tengqm 2016-08-19 03:46:09 -04:00
parent 4eee944e9b
commit 84b1d89a80
15 changed files with 380 additions and 272 deletions

26
api-ref/source/v1/build-info.inc

@ -4,9 +4,6 @@
Build info
==========
Show build information
======================
@ -14,26 +11,35 @@ Show build information
Shows build information for an Orchestration deployment.
Response Codes
--------------
Normal response codes: 200
Error response codes:
.. rest_status_code:: success status.yaml
- 200
Request
-------
.. rest_status_code:: error status.yaml
- 401
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- api: build_api
- engine: build_engine
Response Example
----------------
.. literalinclude:: samples/build-info-response.json
:language: javascript

38
api-ref/source/v1/heat-versions.inc

@ -1,38 +0,0 @@
.. -*- rst -*-
============
API versions
============
List versions
=============
.. rest_method:: GET /
Lists all Orchestration API versions.
Normal response codes: 200
Error response codes:
Request
-------
This operation does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/heat-versions-response.json
:language: javascript

16
api-ref/source/v1/index.rst

@ -22,14 +22,14 @@ Orchestration Service API v1
.. include:: build-info.inc
.. include:: general-info.inc
.. include:: heat-versions.inc
.. include:: resource-types.inc
.. include:: service-status.inc
.. include:: software-config.inc
.. include:: stack-actions.inc
.. include:: stack-events.inc
.. include:: stack-resources.inc
.. include:: stack-templates.inc
.. include:: versions.inc
.. include:: stacks.inc
.. include:: stack-resources.inc
.. include:: stack-outputs.inc
.. include:: stack-snapshots.inc
.. include:: stack-actions.inc
.. include:: stack-events.inc
.. include:: stack-templates.inc
.. include:: software-config.inc
.. include:: resource-types.inc
.. include:: service-status.inc

221
api-ref/source/v1/parameters.yaml

@ -2,7 +2,7 @@
location:
type: string
in: header
required: True
required: true
description: |
For asynchronous resource operations, the ``location`` header contains a
URI that can be checked to track resource status changes.
@ -10,6 +10,7 @@ location:
request_id:
type: UUID
in: header
required: true
description: |
A unique ID for tracking service request. The request ID associated
with the request by default appears in the service logs.
@ -82,13 +83,13 @@ tenant_id:
The UUID of the tenant. A tenant is also known as
a project.
in: path
required: True
required: true
type: string
type_name:
description: |
The name of a resource type.
in: path
required: false
required: true
type: string
# variables in query
@ -132,14 +133,6 @@ marker:
in: query
required: false
type: string
name:
description: |
Filters the response by a resource type name. You
can set this value to a regular expression. Use this filter
multiple times to filter by multiple names.
in: query
required: false
type: string
nested_depth:
description: |
Includes resources from nested stacks up to the
@ -201,7 +194,7 @@ resource_status:
in: query
required: false
type: string
resource_type:
resource_type_query:
description: |
Stack resource type. Valid resource types include ``OS::Cinder::Volume``,
``OS::Nova::Server``, ``OS::Neutron::Port`` and so on.
@ -285,13 +278,11 @@ stack_user_query:
in: query
required: false
type: string
support_status_1:
support_status_query:
description: |
Filters the response by resource types by a
support status. Valid support status values are ``UNKNOWN``,
``SUPPORTED``, ``DEPRECATED``, ``UNSUPPORTED``, and ``HIDDEN``.
Use this filter multiple times to filter by multiple support
statuses.
Filters the response by resource types by a support status. Valid support
status values are ``UNKNOWN``, ``SUPPORTED``, ``DEPRECATED``,
``UNSUPPORTED``, and ``HIDDEN``.
in: query
required: false
type: string
@ -311,11 +302,25 @@ tags_query:
in: query
required: false
type: string
version:
template_type:
description: |
Filters the response by resource types by heat
version. For example, ``2016.1`` or ``5.0.0``. Use this filter
multiple times to filter by multiple versions.
Specify the resource template type. The valid types are: ``cfn``, ``hot``.
in: query
required: false
default: cfn
type: string
type_name_query:
description: |
Filters the response by a resource type name. You can set this value to a
regular expression. Use this filter multiple times to filter by multiple
names.
in: query
required: false
type: string
type_version_query:
description: |
Filters the list of resource types by heat version. For example,
``2016.1`` or ``5.0.0``.
in: query
required: false
type: string
@ -329,9 +334,10 @@ with_count:
type: boolean
with_description:
description: |
Either display resource type's description or not. Default is ``false``
Either display resource type's description or not.
in: query
required: false
default: false
type: boolean
with_detail:
description: |
@ -342,50 +348,6 @@ with_detail:
type: boolean
# variables in body
Description:
description: |
The description specified in the template.
in: body
required: true
type: string
HeatTemplateFormatVersion:
description: |
The version of the heat template.
in: body
required: true
type: string
Outputs:
description: |
Key and value pairs that contain output data.
in: body
required: true
type: object
ParameterGroups:
description: |
A list of parameter groups. Each group contains a
list of parameter names.
in: body
required: false
type: array
Parameters:
description: |
Key and value pairs that contain template parameters.
in: body
required: true
type: object
Parameters_1:
description: |
An object that defines all input parameters that
are defined in the template. Indexed by parameter name.
in: body
required: true
type: object
Resources:
description: |
Contain ``KeyPair`` for resource template.
in: body
required: true
type: object
adopt_stack_data:
description: |
Existing resources data to adopt a stack. Data returned by abandon
@ -395,8 +357,7 @@ adopt_stack_data:
type: object
attributes:
description: |
Key and value pairs that contain resource
attributes.
Key and value pairs that contain resource attributes.
in: body
required: true
type: object
@ -406,6 +367,18 @@ binary:
in: body
required: true
type: string
build_api:
description: |
The orchestration API revsion information.
in: body
required: true
type: object
build_engine:
description: |
The orchestration engine revsion information.
in: body
required: true
type: object
cancel_update:
description: |
Specify the ``cancel_update`` action in the
@ -617,7 +590,13 @@ deployment_updated_time:
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: false
required: false
type: string
Description:
description: |
The description specified in the CFN template.
in: body
required: true
type: string
description:
description: |
@ -743,7 +722,13 @@ group_1:
type: string
heat_template_version:
description: |
The version of the heat template.
The version of the orchestration HOT template.
in: body
required: true
type: string
HeatTemplateFormatVersion:
description: |
The version of the orchestration CFN template.
in: body
required: true
type: string
@ -817,12 +802,6 @@ name_1:
in: body
required: false
type: string
name_3:
description: |
The name of the snapshot.
in: body
required: true
type: string
notification_topics:
description: |
List of notification topics for stack.
@ -860,12 +839,11 @@ output_value:
in: body
required: true
type: string
output_values_1:
Outputs:
description: |
Map of output values for the deployment, as
signaled from the server.
Key and value pairs that contain output data for a CFN template.
in: body
required:
required: true
type: object
outputs:
description: |
@ -874,12 +852,19 @@ outputs:
in: body
required: false
type: array
outputs_1:
ParameterGroups:
description: |
A list of software configuration output data.
A list of parameter groups. Each group contains a
list of parameter names.
in: body
required: false
type: array
Parameters:
description: |
Key and value pairs that contain CFN template parameters.
in: body
required: true
type: array
type: object
parameters:
description: |
Supplies arguments for parameters defined in the stack template.
@ -1012,8 +997,7 @@ project_id:
type: string
properties:
description: |
The properties of the resource. Includes
description, type, and so on.
The properties of the resource. Includes description, type, and so on.
in: body
required: true
type: object
@ -1051,12 +1035,6 @@ resource_changes:
in: body
required: true
type: object
resource_description:
description: |
Displays resource type's description.
in: body
required: false
type: string
resource_name:
description: |
The name of the resource.
@ -1075,18 +1053,43 @@ resource_status_reason:
in: body
required: true
type: string
resource_type_1:
resource_type:
description: |
The type of the resource.
The type name of the resource.
in: body
required: true
type: string
resources:
resource_type_description:
description: |
A list of resources and their properties.
The textual description of the resource type.
in: body
required: true
type: string
resource_types_advanced:
description: |
A list of objects each of which provides the resource type name and a
textual description about the type.
in: body
required: true
type: array
resource_types_simple:
description: |
A list of resource type names.
in: body
required: true
type: array
resources:
description: |
A map of resource names and their properties.
in: body
required: true
type: array
Resources:
description: |
A map containging all resource definitions for the resource template.
in: body
required: true
type: object
resources_2:
description: |
The snapshot resources.
@ -1121,11 +1124,16 @@ services:
type: array
snapshot:
description: |
Key and value pairs that contain snapshot
properties.
Key and value pairs that contain snapshot properties.
in: body
required: true
type: object
snapshot_name:
description: |
The name of the snapshot.
in: body
required: true
type: string
snapshots:
description: |
A list of snapshots and their properties.
@ -1318,7 +1326,7 @@ status_reason_2:
type: string
support_status:
description: |
Information about the current status.
Information about the current support status of a resource type.
in: body
required: true
type: object
@ -1364,12 +1372,6 @@ template_description:
in: body
required: true
type: string
template_description_show:
description: |
The description of the stack template.
in: body
required: false
type: string
template_outputs:
description: |
Key and value pairs that contain output data.
@ -1479,4 +1481,11 @@ updated_time:
in: body
required: true
type: string
versions:
description: |
A list of all orchestration API versions. Each object in the list provides
information about a supported API version such as ``id``, ``status`` and
``links``, among other fields.
in: body
required: true
type: array

145
api-ref/source/v1/resource-types.inc

@ -11,37 +11,63 @@ List resource types
Lists all supported template resource types.
Response Codes
--------------
Normal response codes: 200
Error response codes:401,400,
.. rest_status_code:: success status.yaml
Request
-------
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- name: name
- version: version
- support_status: support_status
- name: type_name_query
- support_status: support_status_query
- version: type_version_query
- with_description: with_description
Response Parameters
-------------------
Note that the format of the response from this API varies when different query
parameters are specified. The default response has the following format:
.. rest_parameters:: parameters.yaml
- template_versions: template_versions
- type: type
- version: version
- description: resource_description
- X-Openstack-Request-Id: request_id
- resource_types: resource_types_simple
When ``with_description`` is specified, the response has the following format:
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- resource_types: resource_types_advanced
- resource_type: resource_type
- description: resource_type_description
Response Example
----------------
The following is an example of the simple response:
.. literalinclude:: samples/resource-types-list-response.json
:language: javascript
The following is an example of the response when ``with_description`` is
specified:
.. literalinclude:: samples/resource-types-list-advanced-response.json
:language: javascript
Show resource type template
===========================
@ -50,51 +76,80 @@ Show resource type template
Shows the template representation for a resource type.
The returned template contains a single resource type. Each
resource property is mapped to a template parameter and each
resource attribute is mapped to a template output.
The returned template contains a single resource type. Each resource property
is mapped to a template parameter and each resource attribute is mapped to a
template output.
You can use these templates as a starting place for creating
customized, template-based resources or as examples of using the
particular resource in another template.
You can use these templates as a starting place for creating customized,
template-based resources or as examples of using the particular resource in
another template.
Use the ``template_type`` query parameter to specify the resource
template type. Default type is ``cfn``. The ``hot`` template type
is supported. For example:
Response Codes
--------------
::
.. rest_status_code:: success status.yaml
/v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn
- 200
.. rest_status_code:: error status.yaml
Normal response codes: 200
Error response codes:404,401,400,
- 400
- 401
- 404
Request
-------
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
- template_type: template_type
Response Parameters
-------------------
The format of the response varies when ``template_type`` is set to different
values. When it is set to ``cfn`` or omitted, the response has the following
format:
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- Description: Description
- Outputs: Outputs
- HeatTemplateFormatVersion: HeatTemplateFormatVersion
- Resources: Resources
- Parameters: Parameters
- Resources: Resources
When the ``template_type`` is explicitly set to ``hot``, the response has the
following format:
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- heat_template_version: heat_template_version
- description: template_description
- outputs: template_outputs
- parameters: template_parameters
- resources: template_resources
Response Example
----------------
The following is a sample of the response when ``template_type`` is set to
``cfn`` or omitted:
.. literalinclude:: samples/resource-type-template-response.json
:language: javascript
The following is a sample of the response when ``template_type`` is explicitly
set to ``hot``:
.. literalinclude:: samples/resource-type-template-hot-response.json
:language: javascript
Show resource type schema
=========================
@ -103,37 +158,41 @@ Show resource type schema
Shows the interface schema for a resource type.
A schema describes the properties that can be set on the resource,
their types, constraints, descriptions, and default values.
Additionally, the response shows the resource attributes and their
descriptions.
A schema describes the properties that can be set on the resource, their types,
constraints, descriptions, and default values. Additionally, the response
shows the resource attributes and their descriptions.
Normal response codes: 200
Error response codes:401,400,
Response Codes
--------------
Request
-------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- type_name: type_name
- with_description: with_description
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: description
- required: required
- update_allowed: update_allowed
- support_status: support_status
- X-Openstack-Request-Id: request_id
- attributes: attributes
- type: type
- properties: properties
- description: resource_description
- resource_type: resource_type
- support_status: support_status
Response Example
----------------

57
api-ref/source/v1/samples/resource-type-template-hot-response.json Normal file

@ -0,0 +1,57 @@
{
"description": "Initial template of KeyPair",
"heat_template_version": "2016-10-14",
"outputs": {
"private_key": {
"description": "The private key if it has been saved.",
"value": "{\"get_attr\": [\"KeyPair\", \"private_key\"]}"
},
"public_key": {
"description": "The public key.",
"value": "{\"get_attr\": [\"KeyPair\", \"public_key\"]}"
},
"show": {
"description": "Detailed information about resource.",
"value": "{\"get_attr\": [\"KeyPair\", \"show\"]}"
}
},
"parameters": {
"name": {
"constraints": [
{
"length": {
"max": 255,
"min": 1
}
}
],
"description": "The name of the key pair.",
"type": "string"
},
"public_key": {
"description": "The optional public key. This allows users to supply the public key from a pre-existing key pair. If not supplied, a new key pair will be generated.",
"type": "string"
},
"save_private_key": {
"default": false,
"description": "True if the system should remember a generated private key; False otherwise.",
"type": "boolean"
}
},
"resources": {
"KeyPair": {
"properties": {
"name": {
"get_param": "name"
},
"public_key": {
"get_param": "public_key"
},
"save_private_key": {
"get_param": "save_private_key"
}
},
"type": "OS::Nova::KeyPair"
}
}
}

15
api-ref/source/v1/samples/resource-type-template-response.json

@ -1,4 +1,5 @@
{
"Description": "Initial template of KeyPair",
"HeatTemplateFormatVersion": "2012-12-12",
"Outputs": {
"private_key": {
@ -8,11 +9,17 @@
"public_key": {
"Description": "The public key.",
"Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"public_key\"]}"
},
"show": {
"Description": "Detailed information about resource.",
"Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"show\"]}"
}
},
"Parameters": {
"name": {
"Description": "The name of the key pair.",
"MaxLength": 255,
"MinLength": 1,
"Type": "String"
},
"public_key": {
@ -21,14 +28,14 @@
},
"save_private_key": {
"AllowedValues": [
true,
"True",
"true",
false,
"False",
"false"
],
"Default": false,
"Description": "true if the system should remember a generated private key; false otherwise.",
"Type": "String"
"Description": "True if the system should remember a generated private key; False otherwise.",
"Type": "Boolean"
}
},
"Resources": {

24
api-ref/source/v1/samples/resource-types-list-advanced-response.json Normal file

@ -0,0 +1,24 @@
{
"resource_types": [
{
"description": "No description given",
"resource_type": "AWS::EC2::Instance"
},
{
"description": "Resource for defining which resources can be accessed by users.\n\nNOTE: Now this resource is actually associated with an AWS user resource,\nnot any OS:: resource though it is registered under the OS namespace below.\n\nResource for defining resources that users are allowed to access by the\nDescribeStackResource API.\n",
"resource_type": "OS::Heat::AccessPolicy"
},
{
"description": "A resource to manage scaling of `OS::Heat::AutoScalingGroup`.\n\n**Note** while it may incidentally support\n`AWS::AutoScaling::AutoScalingGroup` for now, please do not use it for that\npurpose and use `AWS::AutoScaling::ScalingPolicy` instead.\n\nResource to manage scaling for `OS::Heat::AutoScalingGroup`, i.e. define\nwhich metric should be scaled and scaling adjustment, set cooldown etc.\n",
"resource_type": "OS::Heat::ScalingPolicy"
},
{
"description": "Represents a child stack to allow composition of templates.",
"resource_type": "AWS::CloudFormation::Stack"
},
{
"description": "Heat Template Resource for Keystone Group.\n\nGroups are a container representing a collection of users. A group itself\nmust be owned by a specific domain, and hence all group names are not\nglobally unique, but only unique to their domain.\n",
"resource_type": "OS::Keystone::Group"
}
]
}

56
api-ref/source/v1/samples/resource-types-list-response.json

@ -2,60 +2,6 @@
"resource_types": [
"AWS::EC2::Instance",
"OS::Heat::ScalingPolicy",
"AWS::CloudFormation::Stack",
"OS::Keystone::Group",
"OS::Glance::Image",
"AWS::EC2::Volume",
"OS::Heat::SoftwareDeployment",
"AWS::AutoScaling::ScalingPolicy",
"AWS::EC2::InternetGateway",
"OS::Heat::SoftwareDeployments",
"AWS::EC2::VolumeAttachment",
"AWS::CloudFormation::WaitConditionHandle",
"OS::Cinder::VolumeAttachment",
"OS::Cinder::EncryptedVolumeType",
"OS::Heat::AutoScalingGroup",
"OS::Nova::FloatingIP",
"OS::Heat::HARestarter",
"OS::Keystone::Project",
"OS::Keystone::Endpoint",
"OS::Heat::InstanceGroup",
"AWS::CloudWatch::Alarm",
"AWS::AutoScaling::AutoScalingGroup",
"OS::Heat::CloudConfig",
"OS::Heat::SoftwareComponent",
"OS::Cinder::Volume",
"OS::Keystone::Service",
"OS::Heat::WaitConditionHandle",
"OS::Heat::SoftwareConfig",
"AWS::CloudFormation::WaitCondition",
"OS::Heat::StructuredDeploymentGroup",
"OS::Heat::RandomString",
"OS::Heat::SoftwareDeploymentGroup",
"OS::Nova::KeyPair",
"OS::Heat::MultipartMime",
"OS::Heat::UpdateWaitConditionHandle",
"OS::Nova::Server",
"AWS::IAM::AccessKey",
"AWS::EC2::SecurityGroup",
"AWS::EC2::EIPAssociation",
"AWS::EC2::EIP",
"OS::Heat::AccessPolicy",
"AWS::IAM::User",
"OS::Heat::WaitCondition",
"OS::Heat::StructuredDeployment",
"AWS::RDS::DBInstance",
"AWS::AutoScaling::LaunchConfiguration",
"OS::Heat::Stack",
"OS::Nova::FloatingIPAssociation",
"OS::Heat::ResourceGroup",
"OS::Heat::StructuredConfig",
"OS::Nova::ServerGroup",
"OS::Heat::StructuredDeployments",
"OS::Keystone::Role",
"OS::Keystone::User",
"AWS::ElasticLoadBalancing::LoadBalancer",
"OS::Nova::Flavor",
"OS::Cinder::VolumeType"
"AWS::CloudFormation::Stack"
]
}

0
api-ref/source/v1/samples/heat-versions-response.json → api-ref/source/v1/samples/versions-list-response.json

4
api-ref/source/v1/stack-events.inc

@ -28,7 +28,7 @@ Request
- resource_action: resource_action
- resource_status: resource_status
- resource_name: resource_name_query
- resource_type: resource_type
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys
@ -113,7 +113,7 @@ Request
- resource_name: resource_name_url
- resource_action: resource_action
- resource_status: resource_status
- resource_type: resource_type
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys

2
api-ref/source/v1/stack-resources.inc

@ -54,7 +54,7 @@ Request Parameters
- with_detail: with_detail
- name: resource_name_query
- status: resource_status
- type: resource_type
- type: resource_type_query
- action: resource_action
- id: logical_resource_id
- physical_resource_id: physical_resource_id

8
api-ref/source/v1/stack-snapshots.inc

@ -22,7 +22,7 @@ Request Parameters
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- name: name
- name: snapshot_name
Request Example
---------------
@ -36,7 +36,7 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- name: snapshot_name
- status_reason: status_reason
- creation_time: creation_time
- data: data
@ -76,7 +76,7 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- name: snapshot_name
- status_reason: status_reason
- creation_time: creation_time
- snapshot: snapshot
@ -117,7 +117,7 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- status: status
- name: name
- name: snapshot_name
- status_reason: status_reason
- creation_time: creation_time
- snapshots: snapshots

2
api-ref/source/v1/stacks.inc

@ -715,7 +715,7 @@ Response Parameters
- heat_template_version: heat_template_version
- outputs: template_outputs
- parameters: template_parameters
- description: template_description_show
- description: template_description
- resources: template_resources
Response Example

38
api-ref/source/v1/versions.inc Normal file

@ -0,0 +1,38 @@
.. -*- rst -*-
============
API versions
============
List versions
=============
.. rest_method:: GET /
Lists all Orchestration API versions.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 300
Request Parameters
------------------
This operation does not accept a request body.
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- versions: versions
Response Example
----------------
.. literalinclude:: samples/versions-list-response.json
:language: javascript