[doc] Add API document for snapshot instances

This patch adds a new API document for snapshot instances.

Change-Id: Ia0cc534e0bfb2ca5e495e575e27e9911c746690b

api-ref/source/index.rst

@@ -14,6 +14,7 @@ Shared File Systems API
 .. include:: share-metadata.inc
 .. include:: share-actions.inc
 .. include:: snapshots.inc
+.. include:: snapshot-instances.inc
 .. include:: share-networks.inc
 .. include:: security-services.inc
 .. include:: share-servers.inc

api-ref/source/parameters.yaml

@@ -119,6 +119,12 @@ snapshot_id_path:
   in: path
   required: true
   type: string
+snapshot_instance_id_path:
+  description: |
+    The UUID of the share snapshot instance.
+  in: path
+  required: true
+  type: string
 tenant_id:
   description: |
     The UUID for the tenant for which you want to
@@ -447,6 +453,12 @@ share_type_query:
   in: query
   required: false
   type: string
+snapshot_id_query:
+  description: |
+    The UUID of the share's base snapshot to filter the request based on.
+  in: query
+  required: false
+  type: string
 snapshot_id_share_response:
   description: |
     The UUID of the snapshot that was used to create
@@ -2150,6 +2162,12 @@ preferred:
   required: true
   type: boolean
   min_version: 2.14
+progress:
+  description: |
+    The progress of the snapshot creation.
+  in: body
+  required: true
+  type: string
 project:
   description: |
     The UUID of the project to which access to the
@@ -2825,8 +2843,7 @@ share_id_4:
   type: string
 share_instance_id_1:
   description: |
-    The UUID of the share instance that owns this
-    export location.
+    The UUID of the share instance.
   in: body
   required: true
   type: string
@@ -3152,7 +3169,8 @@ size_2:
   type: integer
 snapshot_created_at:
   description: |
-    The date and time stamp when the snapshot was created.
+    The date and time stamp when the snapshot or snapshot instance was
+    created.
 
     The date and time stamp format is `ISO 8601
     <https://en.wikipedia.org/wiki/ISO_8601>`_:
@@ -3211,18 +3229,52 @@ snapshot_id:
   in: body
   required: true
   type: string
-snapshot_id_query:
-  description: |
-    The UUID of the share's base snapshot to filter the request based on.
-  in: body
-  required: false
-  type: string
 snapshot_id_request:
   description: |
     The UUID of the share's base snapshot.
   in: body
   required: false
   type: string
+snapshot_instance_id:
+  description: |
+    The UUID of the share snapshot instance.
+  in: body
+  required: false
+  type: string
+snapshot_instance_id_response:
+  description: |
+    The UUID of the share snapshot instance.
+  in: body
+  required: true
+  type: string
+snapshot_instance_status:
+  description: |
+    The snapshot instance status. A valid value is
+    ``available``, ``error``, ``creating``, ``deleting``, and
+    ``error_deleting``, ``restoring``, ``unmanage_starting``,
+    ``unmanage_error``, ``manage_starting``, ``manage_error``.
+  in: body
+  required: true
+  type: string
+snapshot_instance_updated_at:
+  description: |
+    The date and time stamp when the snapshot instance was
+    updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    The ``±hh:mm`` value, if included, returns the time zone as an
+    offset from UTC.
+
+    For example, ``2016-12-31T13:14:15-05:00``.
+  in: body
+  required: true
+  type: string
 snapshot_manage_share_id:
   description: |
     The UUID of the share that has snapshot which

api-ref/source/samples/snapshot-instance-actions-reset-state-request.json

@@ -0,0 +1,5 @@
+{
+    "reset_status": {
+        "status": "available"
+    }
+}

api-ref/source/samples/snapshot-instance-show-response.json

@@ -0,0 +1,14 @@
+{
+    "snapshot_instance":
+    {
+        "status": "available",
+        "share_id": "618599ab-09a1-432d-973a-c102564c7fec",
+        "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a",
+        "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
+        "progress": "100%",
+        "created_at": "2017-08-04T00:44:52.000000",
+        "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd",
+        "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd",
+        "updated_at": "2017-08-04T00:44:54.000000"
+    }
+}

api-ref/source/samples/snapshot-instances-list-response.json

@@ -0,0 +1,9 @@
+{
+    "snapshot_instances": [
+        {
+            "status": "available",
+            "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
+            "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd",
+        }
+    ]
+}

api-ref/source/samples/snapshot-instances-list-with-detail-response.json

@@ -0,0 +1,15 @@
+{
+    "snapshot_instances": [
+        {
+            "status": "available",
+            "share_id": "618599ab-09a1-432d-973a-c102564c7fec",
+            "share_instance_id": "8edff0cb-e5ce-4bab-aa99-afe02ed6a76a",
+            "snapshot_id": "d447de19-a6d3-40b3-ae9f-895c86798924",
+            "progress": "100%",
+            "created_at": "2017-08-04T00:44:52.000000",
+            "id": "275516e8-c998-4e78-a41e-7dd3a03e71cd",
+            "provider_location": "/path/to/fake/snapshot/snapshot_d447de19_a6d3_40b3_ae9f_895c86798924_275516e8_c998_4e78_a41e_7dd3a03e71cd",
+            "updated_at": "2017-08-04T00:44:54.000000"
+        }
+    ]
+}

api-ref/source/snapshot-instances.inc

@@ -0,0 +1,162 @@
+.. -*- rst -*-
+
+==========================================
+Share snapshot instances (since API v2.19)
+==========================================
+
+A share snapshot instance is an internal representation for a snapshot
+of a share. A single snapshot can have multiple snapshot instances if
+the parent share has multiple ``instances``. When a share is replicated
+or is in the process of being migrated, it can live in multiple places
+and each individual location is called an "instance", internally within
+the Shared File Systems service.
+
+By default administrators can list, show information for and explicitly
+set the state of share snapshot instances. Use the ``policy.json`` file
+to grant permissions for these actions to other roles.
+
+
+List share snapshot instances
+=============================
+
+.. rest_method::  GET /v2/{tenant_id}/snapshot-instances
+
+Lists all share snapshot instances.
+
+Normal response codes: 200
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id_path
+   - snapshot_id: snapshot_id_query
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: snapshot_instance_id_response
+   - snapshot_id: snapshot_id
+   - status: snapshot_instance_status
+
+Response example
+----------------
+
+.. literalinclude:: samples/snapshot-instances-list-response.json
+   :language: javascript
+
+
+List share snapshot instances with details
+==========================================
+
+.. rest_method::  GET /v2/{tenant_id}/snapshot-instances/detail
+
+Lists all share snapshot instances with details.
+
+Normal response codes: 200
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id_path
+   - snapshot_id: snapshot_id_query
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: snapshot_instance_id_response
+   - snapshot_id: snapshot_id
+   - created_at: snapshot_created_at
+   - updated_at: snapshot_instance_updated_at
+   - status: snapshot_instance_status
+   - share_id: share_id
+   - share_instance_id: share_instance_id_1
+   - progress: progress
+   - provider_location: snapshot_provider_location
+
+Response example
+----------------
+
+.. literalinclude:: samples/snapshot-instances-list-with-detail-response.json
+   :language: javascript
+
+
+Show share snapshot instance details
+====================================
+
+.. rest_method::  GET /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}
+
+Shows details for a share snapshot instance.
+
+Normal response codes: 200
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id_path
+   - snapshot_instance_id: snapshot_instance_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: snapshot_instance_id_response
+   - snapshot_id: snapshot_id
+   - created_at: snapshot_created_at
+   - updated_at: snapshot_instance_updated_at
+   - status: snapshot_instance_status
+   - share_id: share_id
+   - share_instance_id: share_instance_id_1
+   - progress: progress
+   - provider_location: snapshot_provider_location
+
+Response example
+----------------
+
+.. literalinclude:: samples/snapshot-instance-show-response.json
+   :language: javascript
+
+
+Reset share snapshot instance state
+===================================
+
+.. rest_method::  POST /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}/action
+
+Administrator only. Explicitly updates the state of a share snapshot instance.
+
+Use the ``policy.json`` file to grant permissions for this action
+to other roles.
+
+Normal response codes: 202
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id_path
+   - snapshot_instance_id: snapshot_instance_id_path
+   - status: snapshot_instance_status
+
+Request example
+---------------
+
+.. literalinclude:: samples/snapshot-instance-actions-reset-state-request.json
+   :language: javascript