From 663c4e383fd3f05da640ebf0c110c2c7f220768f Mon Sep 17 00:00:00 2001 From: TommyLike Date: Tue, 1 Aug 2017 17:21:00 +0800 Subject: [PATCH] Correct 'os-show_image_metadata' API document The 'os-show_image_metadata' API is outdated. Rewrite the document, also correct the response codes for image metadata's create/delete APIs. Change-Id: I50a5b3571973564b8b5010b412d94303866e8dcd --- api-ref/source/v2/index.rst | 1 - api-ref/source/v2/os-vol-image-meta-v2.inc | 45 ------------------- api-ref/source/v2/parameters.yaml | 12 +++++ .../samples/image-metadata-show-request.json | 17 +------ .../samples/image-metadata-show-response.json | 35 ++------------- .../source/v2/volumes-v2-volumes-actions.inc | 44 +++++++++++++++++- api-ref/source/v3/index.rst | 1 - api-ref/source/v3/os-vol-image-meta-v3.inc | 45 ------------------- api-ref/source/v3/parameters.yaml | 12 +++++ .../samples/image-metadata-show-request.json | 17 +------ .../samples/image-metadata-show-response.json | 35 ++------------- .../source/v3/volumes-v3-volumes-actions.inc | 41 ++++++++++++++++- 12 files changed, 115 insertions(+), 190 deletions(-) delete mode 100644 api-ref/source/v2/os-vol-image-meta-v2.inc delete mode 100644 api-ref/source/v3/os-vol-image-meta-v3.inc diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 435f53add84..71b9c50f4ed 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -14,7 +14,6 @@ Block Storage API V2 (DEPRECATED) .. include:: consistencygroups-v2.inc .. include:: hosts.inc .. include:: limits.inc -.. include:: os-vol-image-meta-v2.inc .. include:: os-vol-pool-v2.inc .. include:: os-vol-transfer-v2.inc .. include:: qos-specs-v2-qos-specs.inc diff --git a/api-ref/source/v2/os-vol-image-meta-v2.inc b/api-ref/source/v2/os-vol-image-meta-v2.inc deleted file mode 100644 index f6def86b150..00000000000 --- a/api-ref/source/v2/os-vol-image-meta-v2.inc +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- rst -*- - -Volume image metadata extension (os-vol-image-meta) -=================================================== - -Shows image metadata that is associated with a volume. - - -Show image metadata for volume -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. rest_method:: GET /v2/{tenant_id}/os-vol-image-meta - -Shows image metadata for a volume. - -When the request is made, the caller must specify a reference to an -existing storage volume in the ``ref`` element. Each storage driver -may interpret the existing storage volume reference differently but -should accept a reference structure containing either a ``source- -volume-id`` or ``source-volume-name`` element, if possible. - -Normal response codes: 202, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - description: description - - availability_zone: availability_zone - - bootable: bootable - - volume_type: volume_type - - name: name - - volume: volume - - host: host - - ref: ref - - metadata: metadata - - tenant_id: tenant_id - -Request Example ---------------- - -.. literalinclude:: ./samples/image-metadata-show-request.json - :language: javascript diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index cbcfa0554b2..9d8f1cdbd49 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -971,6 +971,12 @@ metadata_7: in: body required: false type: object +metadata_8: + description: | + The image metadata key value pairs. + in: body + required: true + type: object metadata_items: description: | The number of metadata items that are allowed for @@ -1223,6 +1229,12 @@ os-set_image_metadata: in: body required: true type: object +os-show_image_metadata: + description: | + The ``os-show_image_metadata`` action. + in: body + require: true + type: object os-unmanage: description: | The ``os-unmanage`` action. This action removes diff --git a/api-ref/source/v2/samples/image-metadata-show-request.json b/api-ref/source/v2/samples/image-metadata-show-request.json index f84e8261dd9..44c0af3ff2f 100644 --- a/api-ref/source/v2/samples/image-metadata-show-request.json +++ b/api-ref/source/v2/samples/image-metadata-show-request.json @@ -1,18 +1,3 @@ { - "volume": { - "host": "geraint-VirtualBox", - "ref": { - "source-volume-name": "existingLV", - "source-volume-id": "1234" - }, - "name": "New Volume", - "availability_zone": "az2", - "description": "Volume imported from existingLV", - "volume_type": null, - "bootable": true, - "metadata": { - "key1": "value1", - "key2": "value2" - } - } + "os-show_image_metadata": {} } diff --git a/api-ref/source/v2/samples/image-metadata-show-response.json b/api-ref/source/v2/samples/image-metadata-show-response.json index 343ca66bc71..e0fcf3d9af5 100644 --- a/api-ref/source/v2/samples/image-metadata-show-response.json +++ b/api-ref/source/v2/samples/image-metadata-show-response.json @@ -1,33 +1,6 @@ { - "volume": { - "status": "creating", - "user_id": "eae1472b5fc5496998a3d06550929e7e", - "attachments": [], - "links": [ - { - "href": "http://10.0.2.15:8776/v2/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "rel": "self" - }, - { - "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "rel": "bookmark" - } - ], - "availability_zone": "az2", - "bootable": "false", - "encrypted": "false", - "created_at": "2014-07-18T00:12:54.000000", - "description": "Volume imported from existingLV", - "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb", - "volume_type": null, - "name": "New Volume", - "source_volid": null, - "snapshot_id": null, - "metadata": { - "key2": "value2", - "key1": "value1" - }, - "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "size": 0 + "metadata": { + "key1": "value1", + "key2": "value2" } -} +} \ No newline at end of file diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc index 000aa6161f8..bb59a67cef7 100644 --- a/api-ref/source/v2/volumes-v2-volumes-actions.inc +++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc @@ -98,7 +98,7 @@ Set image metadata for volume Sets the image metadata for a volume. Specify the ``os-set_image_metadata`` action in the request body. -Normal response codes: 202, +Normal response codes: 200 Request @@ -130,7 +130,7 @@ Remove image metadata from volume Removes image metadata, by key, from a volume. Specify the ``os-unset_image_metadata`` action in the request body and the ``key`` for the metadata key and value pair that you want to remove. -Normal response codes: 202, +Normal response codes: 200 Request @@ -153,6 +153,46 @@ Request Example +Show image metadata for volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/{project_id}/volumes/{volume_id}/action + +Shows image metadata for a volume. + +Normal response codes: 200 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - volume_id: volume_id_path + - os-vol-image-meta: os-show_image_metadata + +Request Example +--------------- + +.. literalinclude:: ./samples/image-metadata-show-request.json + :language: javascript + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata_8 + +Response Example +---------------- + +.. literalinclude:: ./samples/image-metadata-show-response.json + :language: javascript + + Attach volume to server diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index a4b524bb48c..0ad6f3ae174 100644 --- a/api-ref/source/v3/index.rst +++ b/api-ref/source/v3/index.rst @@ -22,7 +22,6 @@ Block Storage API V3 (CURRENT) .. include:: volumes-v3-volumes-actions.inc .. List the other random volume APIs in just alphabetical order. -.. include:: os-vol-image-meta-v3.inc .. include:: volume-manage.inc .. include:: volumes-v3-snapshots.inc .. include:: snapshot-manage.inc diff --git a/api-ref/source/v3/os-vol-image-meta-v3.inc b/api-ref/source/v3/os-vol-image-meta-v3.inc deleted file mode 100644 index b3d83abdda5..00000000000 --- a/api-ref/source/v3/os-vol-image-meta-v3.inc +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- rst -*- - -Volume image metadata extension (os-vol-image-meta) -=================================================== - -Shows image metadata that is associated with a volume. - - -Show image metadata for a volume -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. rest_method:: GET /v3/{project_id}/os-vol-image-meta - -Shows image metadata for a volume. - -When the request is made, the caller must specify a reference to an -existing storage volume in the ``ref`` element. Each storage driver -may interpret the existing storage volume reference differently but -should accept a reference structure containing either a ``source- -volume-id`` or ``source-volume-name`` element, if possible. - -Normal response codes: 202 - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - description: description - - availability_zone: availability_zone - - bootable: bootable - - volume_type: volume_type - - name: name - - volume: volume - - host: host - - ref: ref - - metadata: metadata - - project_id: project_id_path - -Request Example ---------------- - -.. literalinclude:: ./samples/image-metadata-show-request.json - :language: javascript diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index bdf65ee89ef..2d4721b3ef1 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -1309,6 +1309,12 @@ metadata_7: in: body required: false type: object +metadata_8: + description: | + The image metadata key value pairs. + in: body + required: true + type: object migration_policy: description: | Specify if the volume should be migrated when it is re-typed. @@ -1598,6 +1604,12 @@ os-set_image_metadata: in: body required: true type: object +os-show_image_metadata: + description: | + The ``os-show_image_metadata`` action. + in: body + require: true + type: object os-unmanage: description: | The ``os-unmanage`` action. This action removes diff --git a/api-ref/source/v3/samples/image-metadata-show-request.json b/api-ref/source/v3/samples/image-metadata-show-request.json index f84e8261dd9..44c0af3ff2f 100644 --- a/api-ref/source/v3/samples/image-metadata-show-request.json +++ b/api-ref/source/v3/samples/image-metadata-show-request.json @@ -1,18 +1,3 @@ { - "volume": { - "host": "geraint-VirtualBox", - "ref": { - "source-volume-name": "existingLV", - "source-volume-id": "1234" - }, - "name": "New Volume", - "availability_zone": "az2", - "description": "Volume imported from existingLV", - "volume_type": null, - "bootable": true, - "metadata": { - "key1": "value1", - "key2": "value2" - } - } + "os-show_image_metadata": {} } diff --git a/api-ref/source/v3/samples/image-metadata-show-response.json b/api-ref/source/v3/samples/image-metadata-show-response.json index a53976b9cba..e0fcf3d9af5 100644 --- a/api-ref/source/v3/samples/image-metadata-show-response.json +++ b/api-ref/source/v3/samples/image-metadata-show-response.json @@ -1,33 +1,6 @@ { - "volume": { - "status": "creating", - "user_id": "eae1472b5fc5496998a3d06550929e7e", - "attachments": [], - "links": [ - { - "href": "http://10.0.2.15:8776/v3/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "rel": "self" - }, - { - "href": "http://10.0.2.15:8776/87c8522052ca4eed98bc672b4c1a3ddb/volumes/23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "rel": "bookmark" - } - ], - "availability_zone": "az2", - "bootable": "false", - "encrypted": "false", - "created_at": "2014-07-18T00:12:54.000000", - "description": "Volume imported from existingLV", - "os-vol-tenant-attr:tenant_id": "87c8522052ca4eed98bc672b4c1a3ddb", - "volume_type": null, - "name": "New Volume", - "source_volid": null, - "snapshot_id": null, - "metadata": { - "key2": "value2", - "key1": "value1" - }, - "id": "23cf872b-c781-4cd4-847d-5f2ec8cbd91c", - "size": 0 + "metadata": { + "key1": "value1", + "key2": "value2" } -} +} \ No newline at end of file diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc index 18e45d48c46..502676aabbe 100644 --- a/api-ref/source/v3/volumes-v3-volumes-actions.inc +++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc @@ -141,7 +141,7 @@ Set image metadata for a volume Sets the image metadata for a volume. Specify the ``os-set_image_metadata`` action in the request body. -Normal response codes: 202 +Normal response codes: 200 Request @@ -173,7 +173,7 @@ Remove image metadata from a volume Removes image metadata, by key, from a volume. Specify the ``os-unset_image_metadata`` action in the request body and the ``key`` for the metadata key and value pair that you want to remove. -Normal response codes: 202 +Normal response codes: 200 Request @@ -195,6 +195,43 @@ Request Example +Show image metadata for a volume +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v3/{project_id}/volumes/{volume_id}/action + +Shows image metadata for a volume. + +Normal response codes: 200 + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - volume_id: volume_id_path + - os-vol-image-meta: os-show_image_metadata + +Request Example +--------------- + +.. literalinclude:: ./samples/image-metadata-show-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata_8 + +Response Example +---------------- + +.. literalinclude:: ./samples/image-metadata-show-response.json + :language: javascript