api-ref - events

This patch fixes problems found in stack/resource events APIs. There
were APIs not precisely documented.

Change-Id: Icb98c8406e1ff6428cb7d9af3f98d6f4982f3922
This commit is contained in:
tengqm 2016-08-20 06:51:39 -04:00 committed by Qiming Teng
parent 2286eae3f3
commit 50f38415da
6 changed files with 264 additions and 137 deletions

View File

@ -0,0 +1,214 @@
.. -*- rst -*-
======
Events
======
The orchestration service provides APIs to check the events occurred on a
stack or a specific resource in a stack.
List stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events
Lists events for a stack.
Response Codes
--------------
.. 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
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_action: resource_action_query
- resource_status: resource_status_query
- resource_name: resource_name_query
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
- nested_depth: nested_depth
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- event_time: event_time
- id: event_id
- links: event_links
- logical_resource_id: logical_resource_id
- physical_resource_id: physical_resource_id
- resource_name: resource_name
- resource_status: resource_status
- resource_status_reason: resource_status_reason
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript
Find stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/events
Finds the canonical URL for the event list of a stack.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 302
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
Reponse Parameters
------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- location: location
- code: code
- message: message
- title: title
Response Example
----------------
.. literalinclude:: samples/events-find-response.json
:language: javascript
List resource events
====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events
Lists events for a stack resource.
Response Codes
--------------
.. 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
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_name: resource_name_url
- resource_action: resource_action_query
- resource_status: resource_status_query
- resource_name: resource_name_query
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
- nested_depth: nested_depth
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript
Show event details
==================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id}
Shows details for an event.
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
- stack_id: stack_id_url
- resource_name: resource_name_url
- event_id: event_id_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Openstack-Request-Id: request_id
- event: event
- event_time: event_time
- id: event_id
- links: event_links
- logical_resource_id: logical_resource_id
- physical_resource_id: physical_resource_id
- resource_name: resource_name
- resource_properties: resource_properties
- resource_status: resource_status
- resource_status_reason: resource_status_reason
- resource_type: resource_type
Response Example
----------------
.. literalinclude:: samples/event-show-response.json
:language: javascript

View File

@ -28,7 +28,7 @@ Orchestration Service API v1
.. include:: stack-outputs.inc
.. include:: stack-snapshots.inc
.. include:: stack-actions.inc
.. include:: stack-events.inc
.. include:: events.inc
.. include:: stack-templates.inc
.. include:: software-config.inc
.. include:: resource-types.inc

View File

@ -249,8 +249,7 @@ sort_dir:
type: string
sort_keys:
description: |
Sorts the list by the ``resource_type`` or
``created_at`` key.
Sorts the result list by keys specified in this parameter.
in: query
required: false
type: string
@ -647,6 +646,35 @@ environment_files:
in: body
required: false
type: object
event:
description: |
An map containing the name and values of event properties.
in: body
required: true
type: object
event_id:
description: |
The UUID of the event object.
in: body
required: true
type: string
event_links:
description: |
A list of URLs for the event. Each URL is a JSON object with an ``href``
key indicating the URL and a ``rel`` key indicating its relationship to
the event in question. There may be multiple links returned. The ``self``
relationship identifies the URL of the event itself.
in: body
required: true
type: array
event_time:
description: |
The date and time when the event was created. The date and time stamp
format is `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_:
``CCYY-MM-DDThh:mm:ss``, for example, ``2015-08-27T09:49:58``.
in: body
required: true
type: string
existing:
description:
A boolean specifying whether the service is about to reuse the existing
@ -1078,6 +1106,12 @@ resource_name:
in: body
required: true
type: string
resource_properties:
description: |
A map containing the properties of the resource associated with the event.
in: body
required: true
type: object
resource_status:
description: |
The status of the resource.

View File

@ -0,0 +1,5 @@
{
"code": "302 Found",
"message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd/events?sort_dir=asc\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd/events?sort_dir=asc</a>;\nyou should be redirected automatically.\n\n",
"title": "Found"
}

View File

@ -1,8 +1,8 @@
{
"events": [
{
"resource_name": "port",
"event_time": "2014-07-23T08:14:47Z",
"id": "474bfdf0-a450-46ec-a78a-0c7faa404073",
"links": [
{
"href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/474bfdf0-a450-46ec-a78a-0c7faa404073",
@ -18,14 +18,14 @@
}
],
"logical_resource_id": "port",
"resource_status": "CREATE_FAILED",
"resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found",
"physical_resource_id": null,
"id": "474bfdf0-a450-46ec-a78a-0c7faa404073"
"resource_name": "port",
"resource_status": "CREATE_FAILED",
"resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found"
},
{
"resource_name": "port",
"event_time": "2014-07-23T08:14:47Z",
"id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
"links": [
{
"href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
@ -41,10 +41,10 @@
}
],
"logical_resource_id": "port",
"resource_status": "CREATE_IN_PROGRESS",
"resource_status_reason": "state changed",
"physical_resource_id": null,
"id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c"
"resource_name": "port",
"resource_status": "CREATE_IN_PROGRESS",
"resource_status_reason": "state changed"
}
]
}

View File

@ -1,126 +0,0 @@
.. -*- rst -*-
============
Stack events
============
List stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/events
Lists events for a stack based on filtering parameters like resource
name, status, type, action. These parameters could be used multiple times.
Normal response codes: 200
Error response codes:404,500,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_action: resource_action_query
- resource_status: resource_status_query
- resource_name: resource_name_query
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
- nested_depth: nested_depth
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript
Find stack events
=================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/events
Finds the canonical URL for the event list of a stack.
Error response codes:302,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_name: stack_name_url
Show event details
==================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id}
Shows details for an event.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_name: resource_name_url
- event_id: event_id_url
Response Example
----------------
.. literalinclude:: samples/event-show-response.json
:language: javascript
List resource events
====================
.. rest_method:: GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events
Lists events for a stack resource.
Normal response codes: 200
Error response codes:404,401,400,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- stack_id: stack_id_url
- stack_name: stack_name_url
- resource_name: resource_name_url
- resource_action: resource_action_query
- resource_status: resource_status_query
- resource_type: resource_type_query
- limit: limit
- marker: marker
- sort_keys: sort_keys
- sort_dir: sort_dir
Response Example
----------------
.. literalinclude:: samples/events-list-response.json
:language: javascript