From 55455241422dbc5a647fb02040cf498b9b197b42 Mon Sep 17 00:00:00 2001 From: TommyLike Date: Mon, 20 Mar 2017 15:54:10 +0800 Subject: [PATCH] [Doc] Add documentation for messages API. Add documentation in v3 for messages API. Change-Id: I6f9886c98eec4bb33fa1b4ad5b51a35a36762bfe --- api-ref/source/v3/index.rst | 1 + api-ref/source/v3/messages.inc | 117 ++++++++++++++++++ api-ref/source/v3/parameters.yaml | 71 +++++++++++ .../v3/samples/messages-list-response.json | 43 +++++++ .../v3/samples/messages-show-response.json | 23 ++++ 5 files changed, 255 insertions(+) create mode 100644 api-ref/source/v3/messages.inc create mode 100644 api-ref/source/v3/samples/messages-list-response.json create mode 100644 api-ref/source/v3/samples/messages-show-response.json diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index 43bce33b175..9fddb7096e9 100644 --- a/api-ref/source/v3/index.rst +++ b/api-ref/source/v3/index.rst @@ -16,6 +16,7 @@ Block Storage API V3 (CURRENT) .. include:: group-snapshots.inc .. include:: group-types.inc .. include:: limits.inc +.. include:: messages.inc .. include:: os-vol-image-meta-v3.inc .. include:: os-vol-pool-v3.inc .. include:: os-vol-transfer-v3.inc diff --git a/api-ref/source/v3/messages.inc b/api-ref/source/v3/messages.inc new file mode 100644 index 00000000000..cf902dce87c --- /dev/null +++ b/api-ref/source/v3/messages.inc @@ -0,0 +1,117 @@ +.. -*- rst -*- + +Messages +======== + +Lists all, shows, and deletes messages. + + +Delete message +~~~~~~~~~~~~~~ + +.. rest_method:: DELETE /v3/{project_id}/messages/{message_id} + +Deletes a message. + +Normal response codes: 202 +Error response codes: badRequest(400), itemNotFound(404) + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - message_id: message_id + + +Show message details +~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v3/{project_id}/messages/{message_id} + +Shows details for a message. + + +Normal response codes: 200 +Error response codes: badRequest(400), itemNotFound(404) + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - message_id: message_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - request_id: request_id + - links: links_5 + - message_level: message_level + - event_id: event_id + - created_at: created_at + - guaranteed_until: guaranteed_until + - resource_uuid: resource_uuid + - id: id_8 + - resource_type: resource_type + - user_message: user_message + +Response Example +---------------- + +.. literalinclude:: ./samples/messages-show-response.json + :language: javascript + + +List messages +~~~~~~~~~~~~~ + +.. rest_method:: GET /v3/{project_id}/messages + +Lists all messages. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - sort_key: sort_key + - sort_dir: sort_dir + - limit: limit + - offset: offset + - marker: marker + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - request_id: request_id + - links: links_5 + - message_level: message_level + - event_id: event_id + - created_at: created_at + - guaranteed_until: guaranteed_until + - resource_uuid: resource_uuid + - id: id_8 + - resource_type: resource_type + - user_message: user_message + +Response Example +---------------- + +.. literalinclude:: ./samples/messages-list-response.json + :language: javascript diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index bc72869e1d4..dddfcfb7082 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -191,6 +191,12 @@ marker: in: query required: false type: string +message_id: + description: | + The UUID of the message. + in: query + required: true + type: string metadata_query: description: | Filters results by a metadata key and value pair. @@ -211,6 +217,13 @@ name_volume: in: query required: false type: string +offset: + description: | + Used in conjunction with ``limit`` to return a slice of items. ``offset`` + is where to start in the list. + in: query + required: false + type: integer sort: description: | Comma-separated list of sort keys and optional @@ -612,6 +625,13 @@ encryption_id_body: in: body required: true type: string +event_id: + description: | + The id of the event to this message, this id could + eventually be translated into ``user_message``. + in: body + required: true + type: string extra_specs: description: | A set of key and value pairs that contains the @@ -710,6 +730,13 @@ group_types: in: body required: true type: array +guaranteed_until: + description: | + The expire time of the message, this message could be + be deleted after this time. + in: body + required: false + type: string has_dependent_backups: description: | If this value is ``true``, the backup depends on @@ -785,6 +812,12 @@ id_7: in: body required: true type: integer +id_8: + description: | + The ID for the message. + in: body + required: true + type: integer imageRef: description: | The UUID of the image from which you want to @@ -925,6 +958,12 @@ links_4: in: body required: true type: array +links_5: + description: | + Links for the message. + in: body + required: false + type: array location: description: | Full URL to a service or server. @@ -964,6 +1003,13 @@ maxTotalVolumes: in: body required: true type: integer +message_level: + description: | + The level of the message, possible value is + only 'ERROR' now. + in: body + required: true + type: string metadata: description: | One or more metadata key and value pairs for the @@ -1427,6 +1473,12 @@ replication_status: in: body required: true type: string +request_id: + description: | + The id of the request during which the message was created. + in: body + required: true + type: string reserved: description: | Reserved volume size. Visible only if you set the @@ -1447,6 +1499,19 @@ reset_status: in: body required: true type: object +resource_type: + description: | + The resource type corresponding to ``resource_uuid``. + in: body + required: false + type: string +resource_uuid: + description: | + The UUID of the resource during whose operation the + message was created. + in: body + required: false + type: string restore: description: | A ``restore`` object. @@ -1725,6 +1790,12 @@ user_id: in: body required: true type: string +user_message: + description: | + The translated readable message corresponding to ``event_id``. + in: body + required: false + type: string vendor_name: description: | The name of the vendor. diff --git a/api-ref/source/v3/samples/messages-list-response.json b/api-ref/source/v3/samples/messages-list-response.json new file mode 100644 index 00000000000..020582d3f23 --- /dev/null +++ b/api-ref/source/v3/samples/messages-list-response.json @@ -0,0 +1,43 @@ +{ + "messages": [{ + "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a", + "links": [ + { + "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "self" + }, + { + "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "bookmark" + } + ], + "message_level": "ERROR", + "event_id": "VOLUME_000002", + "created_at": "2014-10-28T00:00:00-00:00", + "guaranteed_until": "2014-10-28T00:00:00-00:00", + "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf", + "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42", + "resource_type": "VOLUME", + "user_message": "No storage could be allocated for this volume request." + },{ + "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a", + "links": [ + { + "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "self" + }, + { + "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "bookmark" + } + ], + "message_level": "ERROR", + "event_id": "VOLUME_000002", + "created_at": "2014-10-28T00:00:00-00:00", + "guaranteed_until": "2014-10-28T00:00:00-00:00", + "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4df4e", + "id": "c506cd4b-9048-43bc-97ef-0d7dec36d5gt", + "resource_type": "VOLUME", + "user_message": "No storage could be allocated for this volume request." + }] +} \ No newline at end of file diff --git a/api-ref/source/v3/samples/messages-show-response.json b/api-ref/source/v3/samples/messages-show-response.json new file mode 100644 index 00000000000..d674f772b39 --- /dev/null +++ b/api-ref/source/v3/samples/messages-show-response.json @@ -0,0 +1,23 @@ +{ + "message": { + "request_id": "req-c1216709-afba-4703-a1a3-22eda88f2f5a", + "links": [ + { + "href": "http://localhost:8776/v3/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "self" + }, + { + "href": "http://localhost:8776/cd609134301246f0a3faa9c3da22082e/messages/c506cd4b-9048-43bc-97ef-0d7dec369b42", + "rel": "bookmark" + } + ], + "message_level": "ERROR", + "event_id": "VOLUME_000002", + "created_at": "2014-10-28T00:00:00-00:00", + "guaranteed_until": "2014-10-28T00:00:00-00:00", + "resource_uuid": "d5f6c517-c3e8-45fe-b994-b11118e4cacf", + "id": "c506cd4b-9048-43bc-97ef-0d7dec369b42", + "resource_type": "VOLUME", + "user_message": "No storage could be allocated for this volume request." + } +} \ No newline at end of file