From 22656d097c172cbd399904df478fc7698154cffd Mon Sep 17 00:00:00 2001 From: zhongjun2 Date: Tue, 17 Jul 2018 11:06:05 +0800 Subject: [PATCH] Add api ref for access rule metadata feature Partially-implements: bp metadata-for-access-rule Change-Id: Icbac8ec427e23f6a781a7d3e682fe4852fa16179 --- api-ref/source/index.rst | 2 + api-ref/source/parameters.yaml | 27 +++- .../share-access-rules-list-response.json | 32 +++++ .../share-access-rules-show-response.json | 17 +++ ...-access-rules-update-metadata-request.json | 7 ++ ...access-rules-update-metadata-response.json | 7 ++ .../share-actions-grant-access-request.json | 6 +- .../share-actions-grant-access-response.json | 6 +- api-ref/source/share-access-rule-metadata.inc | 90 +++++++++++++ api-ref/source/share-access-rules.inc | 119 ++++++++++++++++++ api-ref/source/share-actions.inc | 12 +- 11 files changed, 318 insertions(+), 7 deletions(-) create mode 100644 api-ref/source/samples/share-access-rules-list-response.json create mode 100644 api-ref/source/samples/share-access-rules-show-response.json create mode 100644 api-ref/source/samples/share-access-rules-update-metadata-request.json create mode 100644 api-ref/source/samples/share-access-rules-update-metadata-response.json create mode 100644 api-ref/source/share-access-rule-metadata.inc create mode 100644 api-ref/source/share-access-rules.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 891a3c0666..3168554167 100644 --- a/api-ref/source/index.rst +++ b/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) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 85da812a0b..65a23d72eb 100644 --- a/api-ref/source/parameters.yaml +++ b/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 diff --git a/api-ref/source/samples/share-access-rules-list-response.json b/api-ref/source/samples/share-access-rules-list-response.json new file mode 100644 index 0000000000..cbc941bece --- /dev/null +++ b/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" + } + } + ] +} diff --git a/api-ref/source/samples/share-access-rules-show-response.json b/api-ref/source/samples/share-access-rules-show-response.json new file mode 100644 index 0000000000..5418a718f2 --- /dev/null +++ b/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" + } + } +} diff --git a/api-ref/source/samples/share-access-rules-update-metadata-request.json b/api-ref/source/samples/share-access-rules-update-metadata-request.json new file mode 100644 index 0000000000..c8b7601fb5 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-access-rules-update-metadata-response.json b/api-ref/source/samples/share-access-rules-update-metadata-response.json new file mode 100644 index 0000000000..c8b7601fb5 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-actions-grant-access-request.json b/api-ref/source/samples/share-actions-grant-access-request.json index 6a8d5d66dd..31b78ac743 100644 --- a/api-ref/source/samples/share-actions-grant-access-request.json +++ b/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" + } } } diff --git a/api-ref/source/samples/share-actions-grant-access-response.json b/api-ref/source/samples/share-actions-grant-access-response.json index 30210124ba..d0c261dbb7 100644 --- a/api-ref/source/samples/share-actions-grant-access-response.json +++ b/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" + } } } diff --git a/api-ref/source/share-access-rule-metadata.inc b/api-ref/source/share-access-rule-metadata.inc new file mode 100644 index 0000000000..3acde80346 --- /dev/null +++ b/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 diff --git a/api-ref/source/share-access-rules.inc b/api-ref/source/share-access-rules.inc new file mode 100644 index 0000000000..a98dc007ad --- /dev/null +++ b/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 + ` 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 diff --git a/api-ref/source/share-actions.inc b/api-ref/source/share-actions.inc index e0e97f0d88..17bc653dd5 100644 --- a/api-ref/source/share-actions.inc +++ b/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 ` API + instead of this API from version 2.45 + Response codes --------------