From 9f2d741db9db7e2e3420add441df6bbbd0702c8f Mon Sep 17 00:00:00 2001 From: ashrod98 Date: Thu, 19 Sep 2024 19:16:39 +0000 Subject: [PATCH] [DOC] Add export location metadata documentation Adds documentation to api-ref Adds metadata response parameter to export location show Signed-off-by: ashrod98 Change-Id: I906bbedbc237c0ec1c50b8fb9c4ecc4eb518544a --- api-ref/source/index.rst | 1 + .../export-location-set-metadata-request.json | 9 + ...export-location-set-metadata-response.json | 10 + ...t-location-show-metadata-item-request.json | 5 + ...-location-show-metadata-item-response.json | 5 + ...xport-location-show-metadata-response.json | 6 + ...port-location-update-metadata-request.json | 7 + ...ort-location-update-metadata-response.json | 7 + ...location-update-null-metadata-request.json | 3 + ...ocation-update-null-metadata-response.json | 3 + .../share-export-locations-metadata.inc | 267 ++++++++++++++++++ api-ref/source/share-export-locations.inc | 1 + 12 files changed, 324 insertions(+) create mode 100644 api-ref/source/samples/export-location-set-metadata-request.json create mode 100644 api-ref/source/samples/export-location-set-metadata-response.json create mode 100644 api-ref/source/samples/export-location-show-metadata-item-request.json create mode 100644 api-ref/source/samples/export-location-show-metadata-item-response.json create mode 100644 api-ref/source/samples/export-location-show-metadata-response.json create mode 100644 api-ref/source/samples/export-location-update-metadata-request.json create mode 100644 api-ref/source/samples/export-location-update-metadata-response.json create mode 100644 api-ref/source/samples/export-location-update-null-metadata-request.json create mode 100644 api-ref/source/samples/export-location-update-null-metadata-response.json create mode 100644 api-ref/source/share-export-locations-metadata.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 4c200453dc..29e364eb4f 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -27,6 +27,7 @@ shared file system storage resources. .. include:: limits.inc .. include:: shares.inc .. include:: share-export-locations.inc +.. include:: share-export-locations-metadata.inc .. include:: share-metadata.inc .. include:: share-actions.inc .. include:: snapshots.inc diff --git a/api-ref/source/samples/export-location-set-metadata-request.json b/api-ref/source/samples/export-location-set-metadata-request.json new file mode 100644 index 0000000000..5bdb58d3bd --- /dev/null +++ b/api-ref/source/samples/export-location-set-metadata-request.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/export-location-set-metadata-response.json b/api-ref/source/samples/export-location-set-metadata-response.json new file mode 100644 index 0000000000..61f1b60b05 --- /dev/null +++ b/api-ref/source/samples/export-location-set-metadata-response.json @@ -0,0 +1,10 @@ + +{ + "metadata": { + "aim": "changed_doc", + "project": "my_app", + "key1": "value1", + "new_metadata_key": "new_information", + "key": "value" + } +} diff --git a/api-ref/source/samples/export-location-show-metadata-item-request.json b/api-ref/source/samples/export-location-show-metadata-item-request.json new file mode 100644 index 0000000000..d232c7ad07 --- /dev/null +++ b/api-ref/source/samples/export-location-show-metadata-item-request.json @@ -0,0 +1,5 @@ +{ + "meta": { + "project": "my_app" + } +} diff --git a/api-ref/source/samples/export-location-show-metadata-item-response.json b/api-ref/source/samples/export-location-show-metadata-item-response.json new file mode 100644 index 0000000000..d232c7ad07 --- /dev/null +++ b/api-ref/source/samples/export-location-show-metadata-item-response.json @@ -0,0 +1,5 @@ +{ + "meta": { + "project": "my_app" + } +} diff --git a/api-ref/source/samples/export-location-show-metadata-response.json b/api-ref/source/samples/export-location-show-metadata-response.json new file mode 100644 index 0000000000..f9793457de --- /dev/null +++ b/api-ref/source/samples/export-location-show-metadata-response.json @@ -0,0 +1,6 @@ +{ + "metadata": { + "project": "my_app", + "aim": "doc" + } +} diff --git a/api-ref/source/samples/export-location-update-metadata-request.json b/api-ref/source/samples/export-location-update-metadata-request.json new file mode 100644 index 0000000000..d4559547f4 --- /dev/null +++ b/api-ref/source/samples/export-location-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/export-location-update-metadata-response.json b/api-ref/source/samples/export-location-update-metadata-response.json new file mode 100644 index 0000000000..d4559547f4 --- /dev/null +++ b/api-ref/source/samples/export-location-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/export-location-update-null-metadata-request.json b/api-ref/source/samples/export-location-update-null-metadata-request.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/export-location-update-null-metadata-request.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/samples/export-location-update-null-metadata-response.json b/api-ref/source/samples/export-location-update-null-metadata-response.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/export-location-update-null-metadata-response.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/share-export-locations-metadata.inc b/api-ref/source/share-export-locations-metadata.inc new file mode 100644 index 0000000000..56577cc828 --- /dev/null +++ b/api-ref/source/share-export-locations-metadata.inc @@ -0,0 +1,267 @@ +.. -*- rst -*- + +Export Location metadata (Since API v2.87) +========================================== + +Shows, sets, updates, and unsets export location metadata. + + +Show all export location metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/shares/{share_id}/export_locations/{export_location_id}/metadata + +.. versionadded:: 2.87 + +Shows all the metadata for a export location, as key and value pairs. + +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_id: share_id + - export_location_id: export_location_id_path + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata + +Response example +---------------- + +.. literalinclude:: samples/export-location-show-metadata-response.json + :language: javascript + + +Show export location metadata item +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: GET /v2/shares/{share_id}/export_locations/{export_location_id}/metadata/{key} + +.. versionadded:: 2.87 + +Retrieves a specific metadata item from a export location'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_id: share_id + - export_location_id: export_location_id_path + - key: metadata_key_path + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata_item + +Response example +---------------- + +.. literalinclude:: samples/export-location-show-metadata-item-response.json + :language: javascript + + +Set export location metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: POST /v2/shares/{share_id}/export_locations/{export_location_id}/metadata + +.. versionadded:: 2.87 + +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 + - 409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_id: share_id + - export_location_id: export_location_id_path + - metadata: metadata_request + + +Request example +--------------- + +.. literalinclude:: samples/export-location-set-metadata-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata + +Response example +---------------- + +.. literalinclude:: samples/export-location-set-metadata-response.json + :language: javascript + + +Update export location metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: PUT /v2/shares/{share_id}/export_locations/{export_location_id}/metadata + +.. versionadded:: 2.87 + +Replaces the metadata for a given export location with the metadata (specified +as key-value pairs) in the request object. All pre-existing metadata of the +export location 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_id: share_id + - export_location_id: export_location_id_path + - metadata: metadata_request + + +Request example +--------------- + +.. literalinclude:: samples/export-location-update-metadata-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata + +Response example +---------------- + +.. literalinclude:: samples/export-location-update-metadata-response.json + :language: javascript + + +To delete all existing metadata items on a given export location, the request object +needs to specify an empty metadata object: + +Request example +--------------- + +.. literalinclude:: samples/export-location-update-null-metadata-request.json + :language: javascript + +Response example +---------------- + +.. literalinclude:: samples/export-location-update-null-metadata-response.json + :language: javascript + + +Delete export location metadata item +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rest_method:: DELETE /v2/shares/{share_id}/export_locations/{export_location_id}/metadata/{key} + +.. versionadded:: 2.87 + +Deletes a single metadata item on a export location, 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 + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - share_id: share_id + - export_location_id: export_location_id_path + - key: metadata_key_path diff --git a/api-ref/source/share-export-locations.inc b/api-ref/source/share-export-locations.inc index c8aa3e2877..f7c234321b 100644 --- a/api-ref/source/share-export-locations.inc +++ b/api-ref/source/share-export-locations.inc @@ -104,6 +104,7 @@ Response parameters - preferred: export_location_preferred - created_at: created_at - updated_at: updated_at + - metadata: metadata Response example ----------------