[DOC] Add api reference to share network subnet metadata

Add the api reference to the feature merged in Antelope release cycle
2023.1 share network subnet metadata

Change-Id: I8143c2652dc9024e3fed5e1ea60b16c86de0a5f2
Closes-bug: #2008028

api-ref/source/index.rst

@@ -35,6 +35,7 @@ shared file system storage resources.
 .. include:: share-replica-export-locations.inc
 .. include:: share-networks.inc
 .. include:: share-network-subnets.inc
+.. include:: share-network-subnets-metadata.inc
 .. include:: security-services.inc
 .. include:: share-servers.inc
 .. include:: share-instances.inc

api-ref/source/parameters.yaml

@@ -1711,24 +1711,6 @@ metadata:
   in: body
   required: true
   type: object
-metadata_2:
-  description: |
-    One or more metadata key-value pairs, as a
-    dictionary of strings. For example, ``"project": "my_test", "aim":
-    "testing"``. The share server does not respect case-sensitive key
-    names. For example, ``"key": "v1"`` and ``"KEY": "V1"`` are
-    equivalent. If you specify both key-value pairs, the server sets
-    and returns only the ``"KEY": "V1"`` key-value pair.
-  in: body
-  required: true
-  type: object
-metadata_3:
-  description: |
-    One or more metadata key and value pairs as a
-    dictionary of strings.
-  in: body
-  required: true
-  type: object
 metadata_item:
   description: |
     A single metadata key and value pair.
@@ -1738,11 +1720,22 @@ metadata_item:
 metadata_key_request:
   description: |
     The key of a metadata item. For example, if the metadata on an existing
-    share or access rule is as follows: ``"project": "my_test",
+    resource is as follows: ``"project": "my_test",
     "aim": "testing"``, the keys are "project" and "aim".
   in: body
   required: true
   type: object
+metadata_request:
+  description: |
+    One or more metadata key-value pairs, as a
+    dictionary of strings. For example, ``"project": "my_test", "aim":
+    "testing"``. The share server does not respect case-sensitive key
+    names. For example, ``"key": "v1"`` and ``"KEY": "V1"`` are
+    equivalent. If you specify both key-value pairs, the server sets
+    and returns only the ``"KEY": "V1"`` key-value pair.
+  in: body
+  required: true
+  type: object
 migrate-start:
   description: |
     The ``migrate-start`` object.

api-ref/source/samples/share-network-subnet-set-metadata-request.json

@@ -0,0 +1,5 @@
+{
+    "metadata": {
+        "key1": "value1"
+    }
+}

api-ref/source/samples/share-network-subnet-set-metadata-response.json

@@ -0,0 +1,9 @@
+{
+    "metadata": {
+        "aim": "changed_doc",
+        "project": "my_app",
+        "key1": "value1",
+        "new_metadata_key": "new_information",
+        "key": "value"
+    }
+}

api-ref/source/samples/share-network-subnet-show-metadata-response.json

@@ -0,0 +1,6 @@
+{
+    "metadata": {
+        "project": "my_app",
+        "key": "value"
+    }
+}

api-ref/source/samples/share-network-subnet-update-metadata-request.json

@@ -0,0 +1,7 @@
+{
+    "metadata": {
+        "aim": "changed_doc",
+        "project": "my_app",
+        "new_metadata_key": "new_information"
+    }
+}

api-ref/source/samples/share-network-subnet-update-metadata-response.json

@@ -0,0 +1,7 @@
+{
+    "metadata": {
+        "aim": "changed_doc",
+        "project": "my_app",
+        "new_metadata_key": "new_information"
+    }
+}

api-ref/source/samples/share-network-subnet-update-null-metadata-request.json

@@ -0,0 +1,3 @@
+{
+    "metadata": null
+}

api-ref/source/samples/share-network-subnet-update-null-metadata-response.json

@@ -0,0 +1,3 @@
+{
+    "metadata": null
+}

api-ref/source/samples/share-show-network-subnet-metadata-item-response.json

@@ -0,0 +1,5 @@
+{
+    "meta": {
+        "project": "my_app"
+    }
+}

api-ref/source/share-metadata.inc

@@ -40,7 +40,7 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - metadata: metadata_3
+   - metadata: metadata
 
 Response example
 ----------------
@@ -127,7 +127,7 @@ Request
 
    - project_id: project_id_path
    - share_id: share_id
-   - metadata: metadata_2
+   - metadata: metadata_request
 
 
 Request example
@@ -180,7 +180,7 @@ Request
 
    - project_id: project_id_path
    - share_id: share_id
-   - metadata: metadata_2
+   - metadata: metadata_request
 
 
 Request example
@@ -194,7 +194,7 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - metadata: metadata_3
+   - metadata: metadata
 
 Response example
 ----------------

api-ref/source/share-network-subnets-metadata.inc

@@ -0,0 +1,257 @@
+.. -*- rst -*-
+
+Share network subnets metadata (since API v2.78)
+================================================
+
+Shows, sets, updates, and unsets share network subnets metadata.
+
+
+Show all share network subnets metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata
+
+Shows all share network subnet metadata in the given share network subnet.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-show-metadata-response.json
+   :language: javascript
+
+
+Show share network subnet metadata item
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata/{key}
+
+Retrieves a specific metadata item from a share network subnet's metadata by its key. If
+the specified key does not represent a valid metadata item, the API will
+respond with HTTP 404.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+   - key: metadata_key_request
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - meta: metadata_item
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-show-network-subnet-metadata-item-response.json
+   :language: javascript
+
+
+Set share network subnet metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata
+
+Allows adding new metadata items as key-value pairs. This API will not delete
+pre-existing metadata items. If the request object contains metadata items
+that already exist, they will be updated with new values as specified in the
+request object.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+   - metadata: metadata_request
+
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-network-subnet-set-metadata-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-set-metadata-response.json
+   :language: javascript
+
+
+Update share network subnet metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  PUT /v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata
+
+Replaces the metadata for a given share network subnet with the metadata (specified as
+key-value pairs) in the request object. All pre-existing metadata of the
+share network subnet will be deleted and replaced with the new metadata supplied.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+   - metadata: metadata_request
+
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-network-subnet-update-metadata-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-update-metadata-response.json
+   :language: javascript
+
+
+To delete all existing metadata items on a given share network subnet,
+the request object needs to specify an empty metadata object:
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-network-subnet-update-null-metadata-request.json
+   :language: javascript
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-network-subnet-update-null-metadata-response.json
+   :language: javascript
+
+
+Delete share network subnet metadata item
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v2/share-networks/{share_network_id}/subnets/{share_network_subnet_id}/metadata/{key}
+
+Deletes a single metadata item on a share network subnet, identified by its key. If
+the specified key does not represent a valid metadata item, the API will
+respond with HTTP 404.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_network_id: share_network_id_path
+   - share_network_subnet_id: share_network_subnet_id_path
+   - key: metadata_key_request