From 8931cdc17f0d43ea41c7604215c6aded94cdc0f9 Mon Sep 17 00:00:00 2001 From: renanv Date: Wed, 29 Mar 2023 16:03:14 -0300 Subject: [PATCH] [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 | 1 + api-ref/source/parameters.yaml | 31 +-- ...e-network-subnet-set-metadata-request.json | 5 + ...-network-subnet-set-metadata-response.json | 9 + ...network-subnet-show-metadata-response.json | 6 + ...etwork-subnet-update-metadata-request.json | 7 + ...twork-subnet-update-metadata-response.json | 7 + ...k-subnet-update-null-metadata-request.json | 3 + ...-subnet-update-null-metadata-response.json | 3 + ...network-subnet-metadata-item-response.json | 5 + api-ref/source/share-metadata.inc | 8 +- .../source/share-network-subnets-metadata.inc | 257 ++++++++++++++++++ 12 files changed, 319 insertions(+), 23 deletions(-) create mode 100644 api-ref/source/samples/share-network-subnet-set-metadata-request.json create mode 100644 api-ref/source/samples/share-network-subnet-set-metadata-response.json create mode 100644 api-ref/source/samples/share-network-subnet-show-metadata-response.json create mode 100644 api-ref/source/samples/share-network-subnet-update-metadata-request.json create mode 100644 api-ref/source/samples/share-network-subnet-update-metadata-response.json create mode 100644 api-ref/source/samples/share-network-subnet-update-null-metadata-request.json create mode 100644 api-ref/source/samples/share-network-subnet-update-null-metadata-response.json create mode 100644 api-ref/source/samples/share-show-network-subnet-metadata-item-response.json create mode 100644 api-ref/source/share-network-subnets-metadata.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 5c5efaf122..a54f9f9f44 100644 --- a/api-ref/source/index.rst +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index d715dc4088..7a11ab5d30 100644 --- a/api-ref/source/parameters.yaml +++ b/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. diff --git a/api-ref/source/samples/share-network-subnet-set-metadata-request.json b/api-ref/source/samples/share-network-subnet-set-metadata-request.json new file mode 100644 index 0000000000..282342e6d5 --- /dev/null +++ b/api-ref/source/samples/share-network-subnet-set-metadata-request.json @@ -0,0 +1,5 @@ +{ + "metadata": { + "key1": "value1" + } +} diff --git a/api-ref/source/samples/share-network-subnet-set-metadata-response.json b/api-ref/source/samples/share-network-subnet-set-metadata-response.json new file mode 100644 index 0000000000..5bdb58d3bd --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-network-subnet-show-metadata-response.json b/api-ref/source/samples/share-network-subnet-show-metadata-response.json new file mode 100644 index 0000000000..e41fe9f34a --- /dev/null +++ b/api-ref/source/samples/share-network-subnet-show-metadata-response.json @@ -0,0 +1,6 @@ +{ + "metadata": { + "project": "my_app", + "key": "value" + } +} diff --git a/api-ref/source/samples/share-network-subnet-update-metadata-request.json b/api-ref/source/samples/share-network-subnet-update-metadata-request.json new file mode 100644 index 0000000000..d4559547f4 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-network-subnet-update-metadata-response.json b/api-ref/source/samples/share-network-subnet-update-metadata-response.json new file mode 100644 index 0000000000..d4559547f4 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-network-subnet-update-null-metadata-request.json b/api-ref/source/samples/share-network-subnet-update-null-metadata-request.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/share-network-subnet-update-null-metadata-request.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/samples/share-network-subnet-update-null-metadata-response.json b/api-ref/source/samples/share-network-subnet-update-null-metadata-response.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/share-network-subnet-update-null-metadata-response.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/samples/share-show-network-subnet-metadata-item-response.json b/api-ref/source/samples/share-show-network-subnet-metadata-item-response.json new file mode 100644 index 0000000000..d232c7ad07 --- /dev/null +++ b/api-ref/source/samples/share-show-network-subnet-metadata-item-response.json @@ -0,0 +1,5 @@ +{ + "meta": { + "project": "my_app" + } +} diff --git a/api-ref/source/share-metadata.inc b/api-ref/source/share-metadata.inc index c695ea9951..0c3b2fc742 100644 --- a/api-ref/source/share-metadata.inc +++ b/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 ---------------- diff --git a/api-ref/source/share-network-subnets-metadata.inc b/api-ref/source/share-network-subnets-metadata.inc new file mode 100644 index 0000000000..b23a40f4ac --- /dev/null +++ b/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