[API Doc] Support datastore version number

Change-Id: Ia38f313a87067f664e11b3f61fb60b6ce584e930
Story: 2008358
Task: 41263

9 files changed, 53 insertions, 16 deletions

diff --git a/api-ref/source/datastore-versions.inc b/api-ref/source/datastore-versions.inc
index c431b1b2..1f0daf78 100644
--- a/api-ref/source/datastore-versions.inc
+++ b/api-ref/source/datastore-versions.inc
@@ -275,8 +275,11 @@ Create datastore version
 
 .. rest_method::  POST /v1.0/{project_id}/mgmt/datastore-versions
 
-Admin only API. Register a datastore version, create the datastore if doesn't
-exist.
+Admin only API. Register a datastore version, the datastore is created
+automatically if doesn't exist.
+
+It's allowed to create datastore versions with the same name but different
+version numbers, or vice versa.
 
 Normal response codes: 202
 
@@ -293,6 +296,7 @@ Request
    - image_tags: image_tags
    - active: active
    - default: default
+   - version: version_number
 
 Request Example
 ---------------
@@ -361,6 +365,8 @@ Update datastore version details
 
 Admin only API. Update a specific datastore version.
 
+The version number is not allowed to update.
+
 Normal response codes: 202
 
 Request
@@ -370,6 +376,7 @@ Request
 
    - project_id: project_id
    - datastore_version_id: datastore_version_id
+   - name: datastore_version_name_optional
    - datastore_manager: datastore_type
    - image: image_id
    - image_tags: image_tags
diff --git a/api-ref/source/instances.inc b/api-ref/source/instances.inc
index 1279bc21..0cc834ec 100644
--- a/api-ref/source/instances.inc
+++ b/api-ref/source/instances.inc
@@ -92,11 +92,15 @@ Create database instance
 
 Creates a database instance.
 
-Asynchronously provisions a database instance. You must specify a flavor ID, a
-volume size and the tenant network ID. The service provisions the instance with
-a volume of the requested size, which serves as storage for the database
-instance. The database service can only be access within the tenant network,
-unless the ``access`` parameter is defined.
+Normally, you must specify a flavor ID, a volume size and the network the
+instance is attached to. The service provisions the instance with a volume of
+the requested size, which serves as storage for the database instance.
+
+If creating replica (a secondary instance of the replication cluster), flavor
+and volume size are not needed.
+
+The database service can only be access within the tenant network, unless the
+``access`` parameter is defined.
 
 Normal response codes: 200
 
@@ -115,6 +119,7 @@ Request
     - datastore: datastore1
     - datastore.type: datastore_type
     - datastore.version: datastore_version
+    - datastore.version_number: version_number
     - name: instanceName1
     - flavorRef: flavorRef
     - volume: volume
@@ -166,6 +171,7 @@ Response Parameters
    - datastore: datastore2
    - datastore.type: datastore_type
    - datastore.version: datastore_version1
+   - datastore.version_number: version_number
    - volume: volume
    - volume.size: volume_size
    - volume.used: volume_used
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 101f15d2..20a0123b 100755
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -74,7 +74,8 @@ user_project:
   type: string
 version:
   description: |
-    Name or ID of the datastore version.
+    Name or ID of the datastore version. If there are multiple datastore
+    versions with the same name but different version numbers, ID is needed.
   in: path
   required: false
   type: string
@@ -353,10 +354,18 @@ datastore_version_id1:
   type: string
 datastore_version_name:
   description: |
-    The name of the datastore version.
+    The name of the datastore version. Different datastore versions can have
+    the same name.
   in: body
   required: true
   type: string
+datastore_version_name_optional:
+  description: |
+    The name of the datastore version. Different datastore versions can have
+    the same name.
+  in: body
+  required: false
+  type: string
 default:
   description: |
     When true this datastore version is created as the default in the
@@ -910,6 +919,14 @@ values:
   in: body
   required: true
   type: string
+version_number:
+  description: |
+    The version number for the database. In container based trove instance
+    deployment, the version number is the same as the container image tag,
+    e.g. for MySQL, a valid version number is 5.7.30
+  in: body
+  required: false
+  type: string
 volume:
   description: |
     A ``volume`` object.
diff --git a/api-ref/source/samples/datastore-version-create-request.json b/api-ref/source/samples/datastore-version-create-request.json
index 9107eb63..32f4d26d 100644
--- a/api-ref/source/samples/datastore-version-create-request.json
+++ b/api-ref/source/samples/datastore-version-create-request.json
@@ -3,9 +3,10 @@
         "datastore_name": "mysql",
         "datastore_manager": "mysql",
         "name": "test",
-        "image": "58b83318-cb18-4189-8d89-a015dc3839dd",
+        "image_tags": ["trove"],
         "active": true,
         "default": false,
-        "packages": []
+        "packages": [],
+        "version": "5.7.30"
     }
 }
\ No newline at end of file
diff --git a/api-ref/source/samples/datastore-version-list-response.json b/api-ref/source/samples/datastore-version-list-response.json
index 4c20d87a..3b526914 100644
--- a/api-ref/source/samples/datastore-version-list-response.json
+++ b/api-ref/source/samples/datastore-version-list-response.json
@@ -13,7 +13,8 @@
                     "rel": "bookmark"
                 }
             ],
-            "name": "12"
+            "name": "12",
+            "version": "5.7.29"
         }
     ]
 }
\ No newline at end of file
diff --git a/api-ref/source/samples/datastore-version-mgmt-list-response.json b/api-ref/source/samples/datastore-version-mgmt-list-response.json
index 47e363fd..51074a12 100644
--- a/api-ref/source/samples/datastore-version-mgmt-list-response.json
+++ b/api-ref/source/samples/datastore-version-mgmt-list-response.json
@@ -11,7 +11,8 @@
             "name": "10.4-dev-train",
             "packages": [
                 ""
-            ]
+            ],
+            "version": "10.4.12"
         },
         {
             "active": true,
@@ -24,7 +25,8 @@
             "name": "12",
             "packages": [
                 ""
-            ]
+            ],
+            "version": "12.4"
         }
     ]
 }
\ No newline at end of file
diff --git a/api-ref/source/samples/datastore-version-mgmt-patch-request.json b/api-ref/source/samples/datastore-version-mgmt-patch-request.json
index 85b98a22..c1a30981 100644
--- a/api-ref/source/samples/datastore-version-mgmt-patch-request.json
+++ b/api-ref/source/samples/datastore-version-mgmt-patch-request.json
@@ -1,4 +1,5 @@
 {
+    "name": "new name",
     "image": "42706631-3b76-4d1c-95c9-6a85e72eebda",
     "active": true
 }
\ No newline at end of file
diff --git a/api-ref/source/samples/datastore-version-mgmt-show-response.json b/api-ref/source/samples/datastore-version-mgmt-show-response.json
index 8f1b78bf..3535d480 100644
--- a/api-ref/source/samples/datastore-version-mgmt-show-response.json
+++ b/api-ref/source/samples/datastore-version-mgmt-show-response.json
@@ -10,6 +10,7 @@
         "name": "10.4-dev-train",
         "packages": [
             ""
-        ]
+        ],
+        "version": "10.4.12"
     }
 }
\ No newline at end of file
diff --git a/api-ref/source/samples/datastore-version-show-response.json b/api-ref/source/samples/datastore-version-show-response.json
index f1798820..bf6ca44e 100644
--- a/api-ref/source/samples/datastore-version-show-response.json
+++ b/api-ref/source/samples/datastore-version-show-response.json
@@ -12,6 +12,7 @@
                 "rel": "bookmark"
             }
         ],
-        "name": "12"
+        "name": "12",
+        "version": "5.7.29"
     }
 }
\ No newline at end of file