From b39bc70093f0d263e7df6d144a785a5b3b58ea25 Mon Sep 17 00:00:00 2001 From: Goutham Pacha Ravi Date: Fri, 26 Jul 2019 15:00:21 -0700 Subject: [PATCH] [api-ref] Correct share metadata API ref - Clarify the difference between PUT and POST on the /shares//metadata URL - Add ref for API to retrieve a single metadata item - Add more notes regarding API behavior Partial-Bug: #1760644 Change-Id: Ic976e0436584b86938c96db571022e96b4592d1f --- api-ref/source/parameters.yaml | 8 +- .../share-show-metadata-item-response.json | 5 ++ .../share-update-null-metadata-request.json | 3 + .../share-update-null-metadata-response.json | 3 + api-ref/source/share-metadata.inc | 88 ++++++++++++++++--- 5 files changed, 95 insertions(+), 12 deletions(-) create mode 100644 api-ref/source/samples/share-show-metadata-item-response.json create mode 100644 api-ref/source/samples/share-update-null-metadata-request.json create mode 100644 api-ref/source/samples/share-update-null-metadata-response.json diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 41a7fe359a..2559481b11 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1363,13 +1363,19 @@ metadata_3: in: body required: true type: object +metadata_item: + description: | + A single metadata key and value pair. + in: body + required: true + type: object 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", "aim": "testing"``, the keys are "project" and "aim". in: body - required: false + required: true type: object migrate-start: description: | diff --git a/api-ref/source/samples/share-show-metadata-item-response.json b/api-ref/source/samples/share-show-metadata-item-response.json new file mode 100644 index 0000000000..d232c7ad07 --- /dev/null +++ b/api-ref/source/samples/share-show-metadata-item-response.json @@ -0,0 +1,5 @@ +{ + "meta": { + "project": "my_app" + } +} diff --git a/api-ref/source/samples/share-update-null-metadata-request.json b/api-ref/source/samples/share-update-null-metadata-request.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/share-update-null-metadata-request.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/samples/share-update-null-metadata-response.json b/api-ref/source/samples/share-update-null-metadata-response.json new file mode 100644 index 0000000000..fe0b27c920 --- /dev/null +++ b/api-ref/source/samples/share-update-null-metadata-response.json @@ -0,0 +1,3 @@ +{ + "metadata": null +} diff --git a/api-ref/source/share-metadata.inc b/api-ref/source/share-metadata.inc index 867e54a16d..1fb313b247 100644 --- a/api-ref/source/share-metadata.inc +++ b/api-ref/source/share-metadata.inc @@ -7,12 +7,12 @@ Share metadata Shows, sets, updates, and unsets share metadata. -Show share metadata -=================== +Show all share metadata +======================= .. rest_method:: GET /v2/{project_id}/shares/{share_id}/metadata -Shows the metadata for a share. +Shows all the metadata for a share, as key and value pairs. Response codes -------------- @@ -50,12 +50,61 @@ Response example :language: javascript +Show share metadata item +========================= + +.. rest_method:: GET /v2/{project_id}/shares/{share_id}/metadata/{key} + +Retrieves a specific metadata item from a share'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 + - key: metadata_key_request + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - metadata: metadata_item + +Response example +---------------- + +.. literalinclude:: samples/share-show-metadata-item-response.json + :language: javascript + + Set share metadata ================== .. rest_method:: POST /v2/{project_id}/shares/{share_id}/metadata -Sets the metadata on a share. +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 -------------- @@ -107,7 +156,9 @@ Update share metadata .. rest_method:: PUT /v2/{project_id}/shares/{share_id}/metadata -Updates the metadata for a share. +Replaces the metadata for a given share with the metadata (specified as +key-value pairs) in the request object. All pre-existing metadata of the +share will be deleted and replaced with the new metadata supplied. Response codes -------------- @@ -153,15 +204,30 @@ Response example :language: javascript -Unset share metadata -==================== +To delete all existing metadata items on a given share, the request object +needs to specify an empty metadata object: + +Request example +--------------- + +.. literalinclude:: samples/share-update-null-metadata-request.json + :language: javascript + +Response example +---------------- + +.. literalinclude:: samples/share-update-null-metadata-response.json + :language: javascript + + +Delete share metadata item +========================== .. rest_method:: DELETE /v2/{project_id}/shares/{share_id}/metadata/{key} -Un-sets the metadata on a share. - -To unset a metadata key value, specify only the key name in the -URI. +Deletes a single metadata item on a share, idetified by its key. If +the specified key does not represent a valid metadata item, the API will +respond with HTTP 404. Response codes --------------