Add api ref for access rule metadata feature

Partially-implements: bp metadata-for-access-rule
Change-Id: Icbac8ec427e23f6a781a7d3e682fe4852fa16179

api-ref/source/index.rst

@@ -28,6 +28,8 @@ Shared File Systems API
 .. include:: quota-sets.inc
 .. include:: quota-classes.inc
 .. include:: user-messages.inc
+.. include:: share-access-rules.inc
+.. include:: share-access-rule-metadata.inc
 
 ======================================
 Shared File Systems API (EXPERIMENTAL)

api-ref/source/parameters.yaml

@@ -2,6 +2,12 @@
 #{}
 
 # variables in path
+access_id_path:
+  description: |
+    The UUID of the access rule to which access is granted.
+  in: path
+  required: true
+  type: string
 api_version:
   in: path
   required: true
@@ -32,6 +38,14 @@ message_id:
   in: path
   required: false
   type: string
+metadata_key_path:
+  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",
+    "aim": "testing"``, the keys are "project" and "aim".
+  in: path
+  required: false
+  type: string
 quota_class_name:
   description:
     The name of the quota class for which to set quotas.
@@ -532,6 +546,13 @@ access_list:
   in: body
   required: true
   type: string
+access_metadata:
+  description: |
+    One or more access rule metadata key and value pairs as a
+    dictionary of strings.
+  in: body
+  required: true
+  type: object
 access_rule_created_at:
   description: |
     The date and time stamp when the access rule was created.
@@ -1806,9 +1827,9 @@ metadata_3:
   type: object
 metadata_key_request:
   description: |
-    The key of a metadata item. For example, if share metadata is
-    as follows: ``"project": "my_test", "aim": "testing"``, the keys are
-    "project" and "aim".
+    The key of a metadata item. For example, if the metadata on an existing
+    share or access rule is as follows: ``"project": "my_test",
+    "aim": "testing"``, the keys are "project" and "aim".
   in: body
   required: false
   type: object

api-ref/source/samples/share-access-rules-list-response.json

@@ -0,0 +1,32 @@
+{
+    "access_list": [
+        {
+            "access_level": "rw",
+            "state": "error",
+            "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
+            "access_type": "cert",
+            "access_to": "example.com",
+            "access_key": null,
+            "created_at": "2018-07-17T02:01:04.000000",
+            "updated_at": "2018-07-17T02:01:04.000000",
+            "metadata": {
+                "key1": "value1",
+                "key2": "value2"
+            }
+        },
+        {
+            "access_level": "rw",
+            "state": "active",
+            "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
+            "access_type": "ip",
+            "access_to": "0.0.0.0/0",
+            "access_key": null
+            "created_at": "2018-07-16T01:03:21.000000",
+            "updated_at": "2018-07-16T01:03:21.000000",
+            "metadata": {
+                "key3": "value3",
+                "key4": "value4"
+            }
+        }
+    ]
+}

api-ref/source/samples/share-access-rules-show-response.json

@@ -0,0 +1,17 @@
+{
+    "access": {
+        "access_level": "rw",
+        "state": "error",
+        "id": "507bf114-36f2-4f56-8cf4-857985ca87c1",
+        "share_id": "fb213952-2352-41b4-ad7b-2c4c69d13eef",
+        "access_type": "cert",
+        "access_to": "example.com",
+        "access_key": null,
+        "created_at": "2018-07-17T02:01:04.000000",
+        "updated_at": "2018-07-17T02:01:04.000000",
+        "metadata": {
+            "key1": "value1",
+            "key2": "value2"
+        }
+    }
+}

api-ref/source/samples/share-access-rules-update-metadata-request.json

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

api-ref/source/samples/share-access-rules-update-metadata-response.json

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

api-ref/source/samples/share-actions-grant-access-request.json

@@ -2,6 +2,10 @@
     "allow_access": {
         "access_level": "rw",
         "access_type": "ip",
-        "access_to": "0.0.0.0/0"
+        "access_to": "0.0.0.0/0",
+        "metadata":{
+            "key1": "value1",
+            "key2": "value2"
+        }
     }
 }

api-ref/source/samples/share-actions-grant-access-response.json

@@ -7,6 +7,10 @@
         "access_to": "0.0.0.0/0",
         "access_level": "rw",
         "access_key": null,
-        "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452"
+        "id": "a25b2df3-90bd-4add-afa6-5f0dbbd50452",
+        "metadata":{
+            "key1": "value1",
+            "key2": "value2"
+        }
     }
 }

api-ref/source/share-access-rule-metadata.inc

@@ -0,0 +1,90 @@
+.. -*- rst -*-
+
+============================================
+Share access rule metadata (Since API v2.45)
+============================================
+
+Updates, and unsets share access rule metadata.
+
+Update share access rule metadata
+==================================
+
+.. rest_method::  PUT /v2/{tenant_id}/share-access-rules/{access_id}/metadata
+
+Updates the metadata for a share access rule.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: access_metadata
+   - access_id: access_id_path
+   - tenant_id: tenant_id_path
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-access-rules-update-metadata-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: access_metadata
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-access-rules-update-metadata-response.json
+   :language: javascript
+
+
+Unset share access rule metadata
+================================
+
+.. rest_method::  DELETE /v2/{tenant_id}/share-access-rules/{access_id}/metadata/{key}
+
+Un-sets the metadata on a share access rule.
+
+To unset a metadata key value, specify only the key name in the
+URI.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - access_id: access_id_path
+   - tenant_id: tenant_id_path
+   - key: metadata_key_path

api-ref/source/share-access-rules.inc

@@ -0,0 +1,119 @@
+.. -*- rst -*-
+
+.. _get-access-rules-after-2-45:
+
+====================================
+Share access rules (Since API v2.45)
+====================================
+
+Retrieve details about access rules
+
+Describe share access rule
+==========================
+
+.. rest_method::  GET /v2/{tenant_id}/share-access-rules/{access_id}
+
+
+Retrieve details about a specified access rule.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - access_id: access_id_path
+   - tenant_id: tenant_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: access_share_id
+   - created_at: access_rule_created_at
+   - updated_at: access_rule_updated_at
+   - access_type: access_type
+   - access_to: access_to
+   - access_key: access_key
+   - state: state
+   - access_level: access_level
+   - id: access_rule_id
+   - access_metadata: access_metadata
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-access-rules-show-response.json
+   :language: javascript
+
+
+List share access rules
+=======================
+
+.. rest_method::  GET /v2/{tenant_id}/share-access-rules?share_id={share-id}
+
+Lists the share access rules on a share.
+
+.. note::
+  This API replaces the older :ref:`List share access rules
+  <get-access-rules-before-2-45>` API from version 2.45.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+   - share_id: share_id
+   - tenant_id: tenant_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: access_metadata
+   - access_type: access_type
+   - access_key: access_key
+   - access_to: access_to
+   - access_level: access_level
+   - state: state
+   - access_list: access_list
+   - id: access_rule_id
+   - created_at: access_rule_created_at
+   - updated_at: access_rule_updated_at
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-access-rules-list-response.json
+   :language: javascript

api-ref/source/share-actions.inc

@@ -1,5 +1,7 @@
 .. -*- rst -*-
 
+.. _get-access-rules-before-2-45:
+
 =============
 Share actions
 =============
@@ -97,6 +99,7 @@ Request
    - access_to: access_to
    - share_id: share_id
    - tenant_id: tenant_id_path
+   - access_metadata: metadata
 
 Request example
 ---------------
@@ -118,6 +121,7 @@ Response parameters
    - access: access
    - access_level: access_level
    - id: access_rule_id
+   - access_metadata: access_metadata
 
 Response example
 ----------------
@@ -166,14 +170,18 @@ Request example
    :language: javascript
 
 
-List access rules
-=================
+List access rules (versions 1.0 to 2.44)
+========================================
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
 Lists access rules for a share. The Access ID returned is necessary to deny
 access.
 
+.. note::
+  Use :ref:`List share access rules <get-access-rules-after-2-45>` API
+  instead of this API from version 2.45
+
 Response codes
 --------------