openstack/manila
Code Issues Proposed changes

[DOC] Add api reference to share network subnet metadata

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

Change-Id: I8143c2652dc9024e3fed5e1ea60b16c86de0a5f2
Closes-bug: #2008028
This commit is contained in:
renanv 2023-03-29 16:03:14 -03:00
parent 6ac66c1967
commit 8931cdc17f
12 changed files with 319 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/index.rst
View File

@ -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

31
api-ref/source/parameters.yaml
View File

@ -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.

5
api-ref/source/samples/share-network-subnet-set-metadata-request.json Normal file
View File

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

9
api-ref/source/samples/share-network-subnet-set-metadata-response.json Normal file
View File

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

6
api-ref/source/samples/share-network-subnet-show-metadata-response.json Normal file
View File

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

7
api-ref/source/samples/share-network-subnet-update-metadata-request.json Normal file
View File

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

7
api-ref/source/samples/share-network-subnet-update-metadata-response.json Normal file
View File

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

3
api-ref/source/samples/share-network-subnet-update-null-metadata-request.json Normal file
View File

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

3
api-ref/source/samples/share-network-subnet-update-null-metadata-response.json Normal file
View File

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

5
api-ref/source/samples/share-show-network-subnet-metadata-item-response.json Normal file
View File

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

8
api-ref/source/share-metadata.inc
View File

@ -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
----------------

257
api-ref/source/share-network-subnets-metadata.inc Normal file
View File

@ -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