Update v2/info/stores api-ref

Slight rewrite of the stores discovery section of the api-ref to
indicate which elements of the response are optional and to remove
mention of the store type from the descriptions.

Change-Id: I8261de878fcaff1e498f7a3e152df7d980d0560c

3 files changed, 19 insertions, 12 deletions

diff --git a/api-ref/source/v2/discovery-parameters.yaml b/api-ref/source/v2/discovery-parameters.yaml
index 8fe685df6..b4b4d3d6e 100644
--- a/api-ref/source/v2/discovery-parameters.yaml
+++ b/api-ref/source/v2/discovery-parameters.yaml
@@ -3,10 +3,18 @@ stores:
     A list of store objects, where each store object may contain the
     following fields:
 
-    - ``id``
-    - ``description``
-    - ``default``
-    - ``read-only``
+    ``id``
+        Operator-defined identifier for the store.
+    ``description``
+        Operator-supplied description of this store.
+    ``default`` (optional)
+        Only present on the default store.  This is the store where image
+        data is placed if you do not indicate a specific store when supplying
+        data to the Image Service.  (See the :ref:`Image data <image-data>`
+        and :ref:`Interoperable image import <image-import-process>` sections
+        for more information.)
+    ``read-only`` (optional)
+        Included only when the store is read only.
   in: body
   required: true
   type: array
diff --git a/api-ref/source/v2/discovery.inc b/api-ref/source/v2/discovery.inc
index 3aaff2d0c..dff7a7f40 100644
--- a/api-ref/source/v2/discovery.inc
+++ b/api-ref/source/v2/discovery.inc
@@ -70,9 +70,8 @@ as a part of the EXPERIMENTAL Image API v2.8.
 
 .. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
           its use in production systems is currently **not supported**.
-          However we encourage people to use this feature for testing
-          purposes and report the issues so that we can make it stable and
-          fully supported in Stein release.
+          The feature is being finalized during the Train development
+          cycle and is expected to be fully supported in Image API v2.9.
 
 In version 2.7 of the API, this call will return a 404 (Not Found).
 Use the :ref:`API versions call <versions-call>` to determine
diff --git a/api-ref/source/v2/samples/stores-list-response.json b/api-ref/source/v2/samples/stores-list-response.json
index ea7276d6f..2d7583d1f 100644
--- a/api-ref/source/v2/samples/stores-list-response.json
+++ b/api-ref/source/v2/samples/stores-list-response.json
@@ -2,20 +2,20 @@
     "stores": [
         {
             "id":"reliable",
-            "description": "Reliable filesystem store"
+            "description": "More expensive store with data redundancy"
         },
         {
             "id":"fast",
-            "description": "Fast access to rbd store",
+            "description": "Provides quick access to your image data",
             "default": true
         },
         {
             "id":"cheap",
-            "description": "Less expensive rbd store"
+            "description": "Less expensive store for seldom-used images"
         },
         {
-            "id":"read_only_store",
-            "description": "Read only http store",
+            "id":"special",
+            "description": "Need a plausible description here that doesn't expose the store type",
             "read-only": true
         }
     ]