api-ref: verify assisted-volume-snapshots.inc

This completes the verification of os-assisted-volume-snapshots.inc
for all required area(parameter, example, body)

Part of bp:api-ref-in-rst

Change-Id: I9544e9681bcdd83ca5d2bf6b8722db0a71665b8b

api-ref/source/os-assisted-volume-snapshots.inc

@@ -1,17 +1,21 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ==========================================================
  Assisted volume snapshots (os-assisted-volume-snapshots)
 ==========================================================
 
-Creates and deletes snapshots through an emulator/hypervisor. The qcow2
+Creates and deletes snapshots through an emulator/hypervisor. Only qcow2
 file format is supported.
 
+This API is only implemented by the libvirt compute driver.
+
 An internal snapshot that lacks storage such as NFS or GlusterFS can use
 an emulator/hypervisor to add the snapshot feature.
+This is used to enable snapshot of volumes on backends such as NFS or
+GlusterFS by storing data as qcow2 files on these volumes.
+
+This API is only ever called by Cinder, where it is used to create a snapshot
+for drivers that extend the remotefs Cinder driver.
 
 Create Assisted Volume Snapshots
 ================================
@@ -33,9 +37,10 @@ Request
   - snapshot: snapshot
   - volume_id: volume_id
   - create_info: create_info
-  - snapshot_id: snapshot_id
-  - type: type-os-assisted-volume-snapshot
-  - new_file: new_file
+  - create_info.snapshot_id: snapshot_id
+  - create_info.type: type-os-assisted-volume-snapshot
+  - create_info.new_file: new_file
+  - create_info.id: create_info_id
 
 **Example Create Assisted Volume Snapshots: JSON request**
 
@@ -47,8 +52,9 @@ Response
 
 .. rest_parameters:: parameters.yaml
 
-  - id: id
-  - volume_id: volume_id
+  - snapshot: snapshot
+  - id: create_info_id_resp
+  - volumeId: volume_id
 
 **Example Create Assisted Volume Snapshots: JSON response**
 
@@ -64,7 +70,7 @@ Deletes an assisted volume snapshot.
 
 To make this request, add the ``delete_info`` query parameter to the URI, as follows:
 
-DELETE /os-assisted-volume-snapshots?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'
+DELETE /os-assisted-volume-snapshots/421752a6-acf6-4b2d-bc7a-119f9148cd8c?delete_info='{"volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"}'
 
 Normal response codes: 204
 
@@ -76,15 +82,10 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
-  - snapshot_id: snapshot_id
-
-Query Parameters
-~~~~~~~~~~~~~~~~
-
-.. rest_parameters:: parameters.yaml
-
+  - snapshot_id: snapshot_id_path
   - delete_info: delete_info
 
 Response
 --------
+
+No body content is returned on a successful DELETE.

api-ref/source/parameters.yaml

@@ -254,7 +254,7 @@ service_id_path:
   in: path
   required: true
   type: integer
-snapshot_id_2:
+snapshot_id_path:
   description: |
     The UUID of the snapshot.
   in: path
@@ -1163,6 +1163,21 @@ create_info:
   in: body
   required: true
   type: object
+create_info_id:
+  description: |
+    Its an arbitrary string that gets passed back to the user.
+  in: body
+  required: false
+  type: string
+create_info_id_resp:
+  description: |
+    Its the same arbitrary string which was sent in request body.
+    NOTE: This string is passed back to user as it is and not being
+    used in Nova internally. So use snapshot_id instead for further
+    operation on this snapshot.
+  in: body
+  required: true
+  type: string
 createBackup:
   description: |
     The action.
@@ -3494,19 +3509,13 @@ snapshot:
     A partial representation of a snapshot that is used to create a snapshot.
   in: body
   required: true
-  type: string
+  type: object
 snapshot_id:
   description: |
     The snapshot ID.
   in: body
   required: true
   type: string
-snapshot_id_1:
-  description: |
-    The unique identifier for a snapshot.
-  in: body
-  required: true
-  type: string
 source_type:
   description: |
     The source type of the volume. A valid value is ``blank``, ``snapshot``, ``volume``,

doc/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-req.json

@@ -4,7 +4,8 @@
         "create_info": {
             "snapshot_id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
             "type": "qcow2",
-            "new_file": "new_file_name"
+            "new_file": "new_file_name",
+            "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
         }
     }
 }

doc/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-resp.json

@@ -1,6 +1,6 @@
 {
     "snapshot": {
-        "id": 100,
+        "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
         "volumeId": "521752a6-acf6-4b2d-bc7a-119f9148cd8c"
     }
 }

nova/tests/functional/api_sample_tests/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-req.json.tpl

@@ -4,7 +4,8 @@
         "create_info": {
             "snapshot_id": "%(snapshot_id)s",
             "type": "%(type)s",
-            "new_file": "%(new_file)s"
+            "new_file": "%(new_file)s",
+            "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c"
         }
     }
 }

nova/tests/functional/api_sample_tests/api_samples/os-assisted-volume-snapshots/snapshot-create-assisted-resp.json.tpl

@@ -1,6 +1,6 @@
 {
     "snapshot": {
-        "id": 100,
+        "id": "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
         "volumeId": "%(uuid)s"
     }
 }

nova/tests/unit/api/openstack/fakes.py

@@ -631,7 +631,8 @@ def stub_snapshot_create(self, context, volume_id, name, description):
 
 
 def stub_compute_volume_snapshot_create(self, context, volume_id, create_info):
-    return {'snapshot': {'id': 100, 'volumeId': volume_id}}
+    return {'snapshot': {'id': "421752a6-acf6-4b2d-bc7a-119f9148cd8c",
+                         'volumeId': volume_id}}
 
 
 def stub_snapshot_delete(self, context, snapshot_id):