From 50f38415da89ae5cc0b00aa17c1ecc2800c26d31 Mon Sep 17 00:00:00 2001 From: tengqm Date: Sat, 20 Aug 2016 06:51:39 -0400 Subject: [PATCH] api-ref - events This patch fixes problems found in stack/resource events APIs. There were APIs not precisely documented. Change-Id: Icb98c8406e1ff6428cb7d9af3f98d6f4982f3922 --- api-ref/source/v1/events.inc | 214 ++++++++++++++++++ api-ref/source/v1/index.rst | 2 +- api-ref/source/v1/parameters.yaml | 38 +++- .../v1/samples/events-find-response.json | 5 + .../v1/samples/events-list-response.json | 16 +- api-ref/source/v1/stack-events.inc | 126 ----------- 6 files changed, 264 insertions(+), 137 deletions(-) create mode 100644 api-ref/source/v1/events.inc create mode 100644 api-ref/source/v1/samples/events-find-response.json delete mode 100644 api-ref/source/v1/stack-events.inc diff --git a/api-ref/source/v1/events.inc b/api-ref/source/v1/events.inc new file mode 100644 index 0000000000..a0fe96a26e --- /dev/null +++ b/api-ref/source/v1/events.inc @@ -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 diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst index c1207cdc9a..46709ae4a8 100644 --- a/api-ref/source/v1/index.rst +++ b/api-ref/source/v1/index.rst @@ -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 diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 33f4714c22..19e3c5f2f5 100644 --- a/api-ref/source/v1/parameters.yaml +++ b/api-ref/source/v1/parameters.yaml @@ -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 `_: + ``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. diff --git a/api-ref/source/v1/samples/events-find-response.json b/api-ref/source/v1/samples/events-find-response.json new file mode 100644 index 0000000000..547bc4e826 --- /dev/null +++ b/api-ref/source/v1/samples/events-find-response.json @@ -0,0 +1,5 @@ +{ + "code": "302 Found", + "message": "The resource was found at http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd/events?sort_dir=asc;\nyou should be redirected automatically.\n\n", + "title": "Found" +} diff --git a/api-ref/source/v1/samples/events-list-response.json b/api-ref/source/v1/samples/events-list-response.json index 83d8f88c4c..4c1533ea37 100644 --- a/api-ref/source/v1/samples/events-list-response.json +++ b/api-ref/source/v1/samples/events-list-response.json @@ -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" } ] } diff --git a/api-ref/source/v1/stack-events.inc b/api-ref/source/v1/stack-events.inc deleted file mode 100644 index 3f6019fc0d..0000000000 --- a/api-ref/source/v1/stack-events.inc +++ /dev/null @@ -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