api-ref: add list manageable resource API

This patch did:
1. Add list manageable volumes API doc.
2. Add create and list manageable snapshots API doc.

Change-Id: Iccffb69b0ffb220f43258ee4c47d5d8964ae7836
Closes-bug: #1590977

api-ref/source/v3/index.rst

@@ -25,6 +25,7 @@ Block Storage API V3 (CURRENT)
 .. include:: os-vol-image-meta-v3.inc
 .. include:: volume-manage.inc
 .. include:: volumes-v3-snapshots.inc
+.. include:: snapshot-manage.inc
 .. include:: os-vol-transfer-v3.inc
 
 .. Now the other random things in alphabetical order.

api-ref/source/v3/parameters.yaml

@@ -85,7 +85,7 @@ hostname:
     The name of the host that hosts the storage back
     end.
   in: path
-  required: false
+  required: true
   type: string
 key_1:
   description: |
@@ -425,6 +425,12 @@ cgsnapshot_id:
   in: body
   required: false
   type: string
+cinder_id:
+  description: |
+    The UUID of the snapshot in Cinder.
+  in: body
+  required: false
+  type: string
 cipher:
   description: |
     The encryption algorithm or mode. For example, aes-xts-plain64. The default
@@ -696,6 +702,12 @@ event_id:
   in: body
   required: true
   type: string
+extra_info:
+  description: |
+    More information about the resource.
+  in: body
+  required: false
+  type: string
 extra_specs:
   description: |
     A set of key and value pairs that contains the
@@ -1047,6 +1059,18 @@ location:
   in: body
   required: true
   type: string
+manageable-snapshots:
+  description: |
+    A list of manageable snapshots.
+  in: body
+  required: true
+  type: list
+manageable-volumes:
+  description: |
+    A list of manageable volumes.
+  in: body
+  required: true
+  type: list
 maxTotalBackupGigabytes:
   description: |
     The maximum total amount of backups, in gibibytes
@@ -1537,6 +1561,12 @@ rate:
   in: body
   required: true
   type: array
+reason_not_safe:
+  description: |
+    The reason why the resource can't be managed.
+  in: body
+  required: false
+  type: string
 ref:
   description: |
     A reference to the existing volume. The internal
@@ -1555,6 +1585,12 @@ ref_1:
   in: body
   required: true
   type: object
+reference:
+  description: |
+    Some information for the resource.
+  in: body
+  required: true
+  type: object
 remove_volumes:
   description: |
     One or more volume UUIDs, separated by commas, to
@@ -1632,6 +1668,12 @@ restore:
   in: body
   required: true
   type: object
+safe_to_manage:
+  description: |
+    If the resource can be managed or not.
+  in: body
+  required: true
+  type: boolean
 security_group_rules:
   description: |
     The number of rules that are allowed for each
@@ -1705,6 +1747,12 @@ snapshot_id_3:
   in: body
   required: true
   type: string
+source-name:
+  description: |
+    The resource's name.
+  in: body
+  required: true
+  type: string
 source_cgid:
   description: |
     The UUID of the source consistency group.
@@ -1717,6 +1765,12 @@ source_group_id:
   in: body
   required: false
   type: string
+source_reference:
+  description: |
+    The snapshot's origin volume information.
+  in: body
+  required: true
+  type: object
 source_replica:
   description: |
     The UUID of the primary volume to clone.

api-ref/source/v3/samples/snapshot-manage-list-detail-response.json

@@ -0,0 +1,29 @@
+{
+  "manageable-snapshots": [
+    {
+      "cinder_id": null,
+      "reason_not_safe": null,
+      "reference": {
+        "source-name": "lvol0"
+      },
+      "source_reference": {
+        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"},
+      "safe_to_manage": true,
+      "size": 1,
+      "extra_info": null
+    },
+    {
+      "cinder_id": "d0c84570-a01f-4579-9789-5e9f266587cd",
+      "reason_not_safe": "already managed",
+      "reference": {
+        "source-name":"_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
+      },
+      "source_reference": {
+        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
+      },
+      "safe_to_manage": false,
+      "size": 1,
+      "extra_info": null
+    }
+  ]
+}

api-ref/source/v3/samples/snapshot-manage-list-response.json

@@ -0,0 +1,24 @@
+{
+  "manageable-snapshots": [
+    {
+      "source_reference": {
+        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
+      },
+      "safe_to_manage": true,
+      "reference": {
+        "source-name": "lvol0"
+      },
+      "size": 1
+    },
+    {
+      "source_reference": {
+        "source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
+      },
+      "safe_to_manage": false,
+      "reference": {
+        "source-name": "_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
+      },
+      "size": 1
+    }
+  ]
+}

api-ref/source/v3/samples/snapshot-manage-request.json

@@ -0,0 +1,11 @@
+{
+  "snapshot": {
+    "description": null,
+    "metadata": null,
+    "ref": {
+      "source-name": "lvol0"
+    },
+    "name": null,
+    "volume_id": "7c064b34-1e4b-40bd-93ca-4ac5a973661b"
+  }
+}

api-ref/source/v3/samples/volume-manage-list-detail-response.json

@@ -0,0 +1,24 @@
+{
+  "manageable-volumes": [
+    {
+      "cinder_id": "9ba5bb53-4a18-4b38-be06-992999da338d",
+      "reason_not_safe": "already managed",
+      "reference": {
+        "source-name": "volume-9ba5bb53-4a18-4b38-be06-992999da338d"
+      },
+      "safe_to_manage": false,
+      "size": 1,
+      "extra_info": null
+    },
+    {
+      "cinder_id": null,
+      "reason_not_safe": null,
+      "reference": {
+        "source-name": "lvol0"
+      },
+      "safe_to_manage": true,
+      "size": 1,
+      "extra_info": null
+    }
+  ]
+}

api-ref/source/v3/samples/volume-manage-list-response.json

@@ -0,0 +1,18 @@
+{
+  "manageable-volumes": [
+    {
+      "safe_to_manage": false,
+      "reference": {
+        "source-name": "volume-3a81fdac-e8ae-4e61-b6a2-2e14ff316f19"
+      },
+      "size": 1
+    },
+    {
+      "safe_to_manage": true,
+      "reference": {
+        "source-name": "lvol0"
+      },
+      "size": 1
+    }
+  ]
+}

api-ref/source/v3/snapshot-manage.inc

@@ -0,0 +1,139 @@
+.. -*- rst -*-
+
+Snapshot manage extension (os-snapshot-manage)
+==============================================
+
+Creates or lists snapshots by using existing storage instead of allocating new
+storage.
+
+
+Manage an existing snapshot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/os-snapshot-manage
+
+Creates a snapshot by using existing storage rather than allocating new storage.
+
+The caller must specify a reference to an existing storage volume
+in the ref parameter in the request. Although each storage driver
+might interpret this reference differently, the driver should
+accept a reference structure that contains either a source-id
+or source-name element, if possible.
+
+The API chooses the size of the snapshot by rounding up the size of
+the existing snapshot to the next gibibyte (GiB).
+
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - description: description
+   - name: name
+   - ref: ref
+   - volume_id: volume_id
+   - metadata: metadata
+   - project_id: project_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/snapshot-manage-request.json
+   :language: javascript
+
+
+
+List summary of snapshots available to manage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/os-snapshot-manage
+
+Search a volume backend and list summary of snapshots which are available to
+manage.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - sort: sort
+   - offset: offset
+   - limit: limit
+   - marker: marker
+   - project_id: project_id_path
+   - host: hostname
+
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - manageable-snapshots: manageable-snapshots
+   - source_reference: source_reference
+   - safe_to_manage: safe_to_manage
+   - reference: reference
+   - source-name: source-name
+   - size: size
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/snapshot-manage-list-response.json
+   :language: javascript
+
+
+
+List detail of snapshots available to manage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/os-snapshot-manage/detail
+
+Search a volume backend and list detail of snapshots which are available to
+manage.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - sort: sort
+   - offset: offset
+   - limit: limit
+   - marker: marker
+   - project_id: project_id_path
+   - host: hostname
+
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - manageable-snapshots: manageable-snapshots
+   - cinder_id: cinder_id
+   - source_reference: source_reference
+   - safe_to_manage: safe_to_manage
+   - reason_not_safe: reason_not_safe
+   - reference: reference
+   - source-name: source-name
+   - size: size
+   - extra_info: extra_info
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/snapshot-manage-list-detail-response.json
+   :language: javascript

api-ref/source/v3/volume-manage.inc

@@ -3,7 +3,7 @@
 Volume manage extension (os-volume-manage)
 ==========================================
 
-Creates volumes by using existing storage instead of allocating new
+Creates or lists volumes by using existing storage instead of allocating new
 storage.
 
 
@@ -55,3 +55,93 @@ Request Example
 
 .. literalinclude:: ./samples/volume-manage-request-cluster.json
    :language: javascript
+
+
+List summary of volumes available to manage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/os-volume-manage
+
+Search a volume backend and list summary of volumes which are available to
+manage.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - sort: sort
+   - offset: offset
+   - limit: limit
+   - marker: marker
+   - project_id: project_id_path
+   - host: hostname
+
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - manageable-volumes: manageable-volumes
+   - safe_to_manage: safe_to_manage
+   - reference: reference
+   - source-name: source-name
+   - size: size
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-manage-list-response.json
+   :language: javascript
+
+
+
+List detail of volumes available to manage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/os-volume-manage/detail
+
+Search a volume backend and list detail of volumes which are available to
+manage.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - sort: sort
+   - offset: offset
+   - limit: limit
+   - marker: marker
+   - project_id: project_id_path
+   - host: hostname
+
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - manageable-volumes: manageable-volumes
+   - cinder_id: cinder_id
+   - safe_to_manage: safe_to_manage
+   - reason_not_safe: reason_not_safe
+   - reference: reference
+   - source-name: source-name
+   - size: size
+   - extra_info: extra_info
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-manage-list-detail-response.json
+   :language: javascript