X-Remove-Object-Meta- is misleading about docs-cloud-files HOT 2 CLOSED

Thanks, �Sam, for reporting this.

CF team,

Can you please take a look at the X-Remove-Object-Meta- at Create or Update Object Metadatahttp://docs.rackspace.com/files/api/v1/cf-devguide/content/POST_updateaobjmeta_v1__account___container___object__objectServicesOperations_d1e000.html and provide your advice about the information in Dev Guide that Sam is referring to?

Sam has also sent another email today to the cfteam list about metadata that might have some impact on what you advise.

Thanks,
--Catherine

Catherine Richardson
Information Developer
Office: 512 874 1156 (internal 506 1156)
Cell: 512 750 0666

From: Sam Harwell <[email protected]mailto:[email protected]>
Reply-To: rackerlabs/docs-cloud-files <[email protected]mailto:[email protected]>
Date: Tuesday, April 29, 2014 6:42 AM
To: rackerlabs/docs-cloud-files <[email protected]mailto:[email protected]>
Subject: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

The documentation for Create or Update Object Metadatahttp://docs.rackspace.com/files/api/v1/cf-devguide/content/POST_updateaobjmeta_v1__account___container___object__objectServicesOperations_d1e000.html mentions the prefix X-Remove-Object-Meta-. The description of this prefix is misleading.

The POST command to set metadata clears all metadata which is not explicitly set in the request. Headers with the prefix X-Remove-Object-Meta- do not change this behavior, whether or not a value is assigned for the header.

?
Reply to this email directly or view it on GitHubhttps://github.com//issues/3.

from docs-cloud-files.

Changes for this will be in the next publish cycle. They have been made locally. See the email thread below:

From: David Goetz [email protected]
Date: Wednesday, May 7, 2014 2:55 PM
To: Catherine Richardson [email protected], Sam Harwell [email protected]
Cc: "[email protected]" [email protected]
Subject: RE: FOR REVIEW: Re: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

Hey Catherine,

I'd just get rid of this paragraph:

As an alternative for deleting one existing metadata header, you can send aPOST request to the object with the header X-Remove-Object-Meta-name: value, where name is the name of the metadata you want to delete and value is any value and is not used. However, you must send a value with the request. Otherwise, the metadata is not removed.

and add a similar paragraph as the one you removed above except about container metadata. Something like:

As an alternative for deleting one existing metadata header, you can send aPOST request to the container with the header X-Remove-Container-Meta-name: value, where name is the name of the metadata you want to delete and value is any value and is not used.

That last part about "However, you must send a value with the request" isn't true- its just curl won't send empty headers.

Is there already something about that in the “Delete Container Metadata” section? If so, then never mind about the extra paragraph. The main idea is that the x-remove-*-meta stuff only really makes sense on account/container metatdata and just confuses stuff on the object level.

David

From: Catherine Richardson
Sent: Wednesday, May 07, 2014 11:33 AM
To: Catherine Richardson; David Goetz; Sam Harwell
Cc: [email protected]
Subject: FOR REVIEW: Re: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

Hi, David

Please review the following and let me know what you think/if you have changes. The highlighted info is new based on your example.

Thanks,
Catherine

Create or Update Object Metadata
.
.
.
You can set or update your custom metadata for existing objects by sending a POST request to the object name.

Metadata is set by using the header X-Object-Meta-name: value, where name is the custom name for your metadata and value is the value.

You can also set values for X-Delete-At and X-Delete-After to set expirations for objects.

For information about working with metadata when copying objects, see Section 5.3.4, “Copy Object”.

Deleting Object Metadata

For objects, the POST request to set metadata deletes all metadata that is not explicitly set in the request. In other words, ALL the object metadata is set at the time of the POST request. If you want to edit or remove one header, include all other headers in the POST request and leave out the header that you want to remove. This means that if you delete one entry without posting the others, the others will also be deleted at that time.

For example, you use a HEAD request to list object metadata and get the following results:

X-Object-Meta-Price: 50
X-Object-Meta-Extra: Data
Then you perform a POST request similar to the following example to set metadata on the same object that you listed above:

POST /v1/account/containName/objectName HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: yourAuthToken
X-Object-Meta-Price: 45
X-Object-Meta-Cost: 30
Listing the object metadata again after the POST then shows the following results and X-Object-Meta-Extra no longer exists.

X-Object-Meta-Price: 45
X-Object-Meta-Cost: 30
As an alternative for deleting one existing metadata header, you can send a POST request to the object with the header X-Remove-Object-Meta-name: value, where name is the name of the metadata you want to delete and value is any value and is not used. However, you must send a value with the request. Otherwise, the metadata is not removed.

To remove all metadata for an object, simply perform a POST request for the object with no metadata specified.

Note that removing container metadata works differently. To remove container metadata, you must send the header with an empty value. For more information, see Section 5.2.6, “Delete Container Metadata”.

Create or Update Container Metadata
.
.
.
Updating Container Metadata
For containers, the POST request to set metadata does not delete existing metadata that is not explicitly set in the request.

For example, you use a HEAD request to list container metadata and get the following results:

X-Container-Meta-Price: 50
X-Container-Meta-Extra: Data
Then you perform a POST request similar to the following example to set metadata on the same container that you listed above:

POST /v1/account/containName HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: yourAuthToken
X-Container-Meta-Price: 45
X-Container-Meta-Cost: 30
Listing the container metadata again after the POST then shows the following results. The X-Container-Meta-Extra metadata still exists:

X-Container-Meta-Price: 45
X-Container-Meta-Cost: 30
X-Container-Meta-Extra: Data
For information about deleting container metadata, see Section 5.2.6, “Delete Container Metadata”.

Note that updating and deleting object metadata works differently. For an example, see Section 5.3.6, “Create or Update Object Metadata”.

Delete Container Metadata
.
.
.
Note that updating and deleting object metadata works differently. For an example, see Section 5.3.6, “Create or Update Object Metadata”.

From: David Goetz [email protected]
Date: Tuesday, April 29, 2014 10:53 AM
To: "[email protected]" [email protected], Catherine Richardson [email protected], Sam Harwell [email protected]
Subject: RE: Remove X-Remove-Object-Meta header from CF Dev Guide? Re: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

I added that header a while back because people were complaining about not being able to remove metadata headers with the old APIs. The remove flag does make sense when you are talking about container metadata because the only other way to remove container metadata with a POST is to send the value as an empty string and curl / some old APIs wouldn't do that. It doesn't make a lot of sense in the context of object metadata because if you don't send the header at all it will be removed. I think the issue got confused somewhere along the way.

We can remove the x-remove-object-meta-* if you want but there should be a better explanation of how the object vrs container/account metadata works. Maybe an example works best. Something like

-X HEAD /a/c/o

x-object-meta-Price: 50
x-object-meta-Extra: Data

-X POST /a/c/o -H "x-object-meta-Price: 45" -H "x-object-meta-Cost: 30"

-X HEAD /a/c/o

x-object-meta-Price: 45
x-object-meta-Cost: 30

verses container:

-X HEAD /a/c

x-container-meta-Price: 50
x-container-meta-Extra: Data

-X POST /a/c -H "x-container-meta-Price: 45" -H "x-container-meta-Cost: 30"

-X HEAD /a/c

x-container-meta-Price: 45
x-container-meta-Cost: 30
x-container-meta-Extra: Data

Or something like that- idk.

David

From: Catherine Richardson [[email protected]]
Sent: Tuesday, April 29, 2014 10:27 AM
To: Catherine Richardson; Sam Harwell; [email protected]
Subject: [cfteam] Remove X-Remove-Object-Meta header from CF Dev Guide? Re: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

The OpenStack Object Storage Reference does not include anything about the X-Remove-Object-Meta header.

Should I remove it from the Rackspace Cloud Files Developer Guide?

Thanks,
--Catherine

From: Catherine Richardson [email protected]
Date: Tuesday, April 29, 2014 8:48 AM
To: rackerlabs/docs-cloud-files reply+i-32437953-59da2ca687e8da8d08bf73e25c627bcfcc32d574-4238838@reply.github.com, Sam Harwell [email protected], "[email protected]" [email protected]
Cc: Catherine Richardson [email protected]
Subject: Re: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

Thanks, Sam, for reporting this.

CF team,

Can you please take a look at the X-Remove-Object-Meta- at Create or Update Object Metadata and provide your advice about the information in Dev Guide that Sam is referring to?

Sam has also sent another email today to the cfteam list about metadata that might have some impact on what you advise.

Thanks,
--Catherine

From: Sam Harwell [email protected]
Reply-To: rackerlabs/docs-cloud-files reply+i-32437953-59da2ca687e8da8d08bf73e25c627bcfcc32d574-4238838@reply.github.com
Date: Tuesday, April 29, 2014 6:42 AM
To: rackerlabs/docs-cloud-files [email protected]
Subject: [docs-cloud-files] X-Remove-Object-Meta- is misleading (#3)

The documentation for Create or Update Object Metadata mentions the prefix X-Remove-Object-Meta-. The description of this prefix is misleading.

The POST command to set metadata clears all metadata which is not explicitly set in the request. Headers with the prefix X-Remove-Object-Meta- do not change this behavior, whether or not a value is assigned for the header.

from docs-cloud-files.