It looks like the Manila code has support to retrieve a single metadata/metadatum: https://github.com/openstack/manila/blob/cec13b8057fa025fa1b1c3bef180687a394d6fd6/manila/api/v1/share_metadata.py#L121

To prevent confusion, let's change this to either Metadata or GetMetadata. Both have been used in Gophercloud before.

+1 GetMetadata corresponds to this project's idioms...

A GetMetadatum call may be useful too, thanks for pointing that out @jtopjian.. It'll make things faster if you're trying to verify if some metadata key exists, or set to a particular value.

If that API call is exposed, I agree. The API documentation doesn't have it listed, but that might just mean it's undocumented :)

Yep! fixing the docs here: https://review.opendev.org/#/c/673112/

refactored ShowMetadata into GetMetadata: da281ed

added GetMetadatum: 66bd2c0

Because this API call is only for a single piece of metadata/metadatum, let's change this to either UnsetMetadatum or DeleteMetadatum. "Metadatum" is used throughout Gophercloud to denote a single piece of metadata.

I went for DeleteMetadatum: 6a073de

Worth calling out the difference between SetMetadata and UpdateMetadata, as a comment for future maintainers:

SetMetadata allows adding new metadata items or updating values of existing metadata items; however, UpdateMetadata will drop existing metadata and replace it with new metadata key=value pairs as specified.

done in 5c226fe

I understand the purpose of this, but let's use the style that has been previously used here: https://github.com/gophercloud/gophercloud/blob/master/openstack/compute/v2/servers/results.go#L346-L352

This returns a map[string]string so the user/dev can do:

result, err := shares.GetMetadatum(c, shareID, "foo").Extract()
fmt.Println(result["foo"])

Once it's updated like this, it looks like GetMetadata, GetMetadatum, SetMetadata, and UpdateMetadata can all share a single result type:

type MetadataResult struct {
  gophercloud.Result
}

func (r MetadataResult) Extract() (map[string]string, error) {
 ...
}

Let me know if this makes sense or if you have any questions.

Actually GetMetadatum would still need a separate result type because it uses meta parent in its JSON response instead of metadata like the other methods use (see example responses for show-metadata VS show-metadata-item). I'll merge the result types for the rest of the methods.

Should GetMetadatumResult then still return map[string]string like you're suggesting, or rather keep things as they are in this PR and return string? I'm totally fine with either, especially if it's to keep things consistent...although the latter seems a bit more user-friendly by not having to repeat the metadata key.

Actually GetMetadatum would still need a separate result type because it uses meta parent in its JSON response instead of metadata like the other methods use

Good catch.

Should GetMetadatumResult then still return map[string]string like you're suggesting,

Yes, please.

I agree that it can be more intuitive to have only the value returned, but using this method keeps things consistent with other metadata areas in Gophercloud. In addition, it more closely models the API response (since the API response is a dict/object/hash).