Object services operations

You can perform the operations in the following table on objects in your Cloud Files containers.

The examples in this section use sample values for the following:

• account — for example, MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123

• X-Auth-Token — for example, f064c46a782c444cb4ba4b6434288f7c

• container — for example, MyContainer

• object — for example, MyObject

For your own requests, you must use your own account information, authentication token, container names, and object names. For more information, see the Authenticate to the Rackspace Cloud section. Your authentication token and your account information are in the service catalog that is produced.

Get object content and metadata

GET /v1/{account}/{container}/{object}

This operation gets the content and metadata for the object.

You can perform conditional GET requests by using the following HTTP headers in the request:

• If-Match

• If-None-Match

• If-Modified-Since

• If-Unmodified-Since

These headers are documented in http://www.ietf.org/rfc/rfc2616.txt.

You can fetch a portion of the data by using the HTTP Range header. To specify multiple ranges, separate the range specifications with a comma.

The types of range specifications are as follows:

• Byte range specification: Use a FIRST_BYTE_OFFSET value to specify the start of the data range, and use a LAST_BYTE_OFFSET value to specify the end of the range. If you omit the LAST_BYTE_OFFSET value, the offset of the last byte of data is used.

• Suffix byte range specification: Use LENGTH bytes to specify the length of the data range.

The following table shows forms of the header and the ranges of data specified.

Cloud Files supported range formats

Header	Range of Object Data
Range: bytes=-5	The last five bytes.
Range: bytes=10-15	The six bytes of data after a 10-byte offset.
Range: bytes=10-15,-5	A multipart response that contains the last five bytes and the six bytes of data after a 10-byte offset. The Content-Type of the response is then multipart/byteranges.
Range: bytes=4-6	Bytes 4 through 6.
Range: bytes=2-2	Byte 2, the third byte of the data.
Range: bytes=6-	Byte 6 and after.
Range: bytes=1-3,2-5	A multipart response that contains bytes 1 through 3, and bytes 2 through 5. The Content-Type of the response is then multipart/byteranges.

Object data is returned in the response body. Object metadata is returned as HTTP headers.

A status code of 200 through 299 indicates success. Status code 404 (Not Found) is returned if the object does not exist.

Note

In the following examples that use ranges, the object contains the 10 bytes of data 0123456789.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request has succeeded. The
404	Not Found	The requested resource was not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.

This table shows the query parameters for the request:

Name	Type	Description
signature	String	Used with temporary URLs to sign the request. For more information about temporary URLs, see TempURL.
expires	String	Used with temporary URLs to specify the expiry time of the signature. For more information about temporary URLs, see TempURL.
multipart- manifest	String	If you include the multipart- manifest=get query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the X-Object- Manifest response header for dynamic large objects or in the response body for static large objects.

This operation does not accept a request body.

Example: Get object data HTTP request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Example: Get object data using a range HTTP request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Range: bytes=4-6

Example: Get object data using multiple ranges HTTP request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Range: bytes=1-3,2-5

Response

This table shows the header parameters for the response:

Name	Type	Description
Content-Length	String	The length of the object content in the response body, in bytes.
Accept-Ranges	String	The type of ranges that the object accepts.
Last-Modified	String	The date and time that the object was created or the last time that the metadata was changed.
ETag	String	For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted. For manifest objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was downloaded. Also the value is enclosed in double-quote characters. You are strongly recommended to compute the MD5 checksum of the response body as it is received and compare this value with the one in the ETag header. If they differ, the content was corrupted, so retry the operation.
Content-Type	String	The MIME type of the object.
Content-Encoding	String	If set, the value of the Content-Encoding metadata. If not set, this header is not returned by this operation.
Content-Disposition	String	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default. If not set, this header is not returned by this operation.
X-Delete-At	String	If set, the time when the object will be deleted by the system in the format of a UNIX epoch timestamp. If not set, this header is not returned by this operation.
X-Object-Meta-name	String	The custom object metadata item, where name is the name of the metadata item. One X-Object-Meta-name response header appears for each metadata item (for each name).
X-Object-Manifest	String	If set, to this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix.
X-Static-Large-Object	Boolean	Set to True if this object is a static large object manifest object.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.

Example: Get object data response

HTTP/1.1 200 OK
Date: Wed, 14 Jul 2010 19:37:41 GMT
Last-Modified: Mon, 12 Jun 2010 13:40:18 GMT
ETag: b0dffe8254d152d8fd28f3c5e0404a10
Content-Type: text/html
Content-Length: 512000

[ ...object content... ]

Example: Get object data using range response

HTTP/1.1 206 Partial Content
Date: Wed, 14 Jul 2010 19:37:41 GMT
Last-Modified: Mon, 12 Jun 2010 13:40:18 GMT
ETag: b0dffe8254d152d8fd28f3c5e0404a10
Content-Type: application/octet-stream
Accept-Ranges: bytes
Content-Range: bytes 4-6/10
Content-Length: 3

456

Example: Get object data using multiple ranges response

HTTP/1.1 206 Partial Content
Date: Wed, 14 Jul 2010 19:37:41 GMT
Last-Modified: Mon, 12 Jun 2010 13:40:18 GMT
ETag: b0dffe8254d152d8fd28f3c5e0404a10
Content-Type: multipart/byteranges;boundary=4789b20f24cc4d2a8da2e552e151e6fe
Accept-Ranges: bytes
Content-Range: bytes 4-6/10
Content-Length: 265

--4789b20f24cc4d2a8da2e552e151e6fe
Content-Type: application/octet-stream
Content-Range: bytes 1-3/10

123
--4789b20f24cc4d2a8da2e552e151e6fe
Content-Type: application/octet-stream
Content-Range: bytes 2-5/10

2345
--4789b20f24cc4d2a8da2e552e151e6fe--

Create or update object

PUT /v1/{account}/{container}/{object}

This operation creates or updates the content and metadata for a specified object.

The PUT operation writes, or overwrites, an object’s content and metadata.

Note

The PUT operation actually always creates a new object. If you use this operation on an existing object, you actually replace the existing object and metadata rather than modifying the object. This is why this operation returns a 201 (Created) status code.

You can ensure end-to-end data integrity by including an MD5 checksum of your object’s data in the ETag header. You are not required to include the ETag header, but we recommend its use to ensure that the storage system successfully stores your object’s content.

You can cause an object to expire after a certain date and time by using the X-Delete-At or X-Delete-After headers during an object PUT operation. The X-Delete-At header requires a Unix epoch timestamp, in integer form. For example, 1348691905 represents Wed, 26 Sep 2012 20:38:25 GMT. By setting the header to a specific epoch time, you indicate when you want the object to expire, not be served, and be deleted completely from the storage system. When Cloud Files detects one of these headers, the system automatically stops serving that object at the specified date and time, and shortly after the expiration date, it removes the object from the storage system.

The HTTP response includes the MD5 checksum of the data written to the storage system. If you do not send the ETag header in the request, you should compare the value returned with your content’s MD5 locally to perform the end-to-end data validation on the client side. For manifest objects, ETag is the MD5 checksum of the concatenated string of ETags for each segment in the manifest, which offers change detection but not direct comparison.

For more information, see Creating large objects.

Note

The best checks for a successful upload are to check the ETag match with a checksum and to see if you get a 404 (Not Found) status code when you perform a GET, HEAD, POST, or DELETE operation.

You can assign custom metadata to objects by including additional HTTP headers in the PUT request. To assign custom metadata, use an HTTP header with the X-Object-Meta- prefix.

You can also specify the Content-Type header for your object. For example, you can specify Content-Type: audio/mpeg3 for MP3 files.

A status code of 201 (Created) indicates a successful write. Any status code in the 400 range denotes failure. The 401 (Unauthorized) status code is returned if authentication fails. The 411 (Length Required) status code denotes a missing Content-Length or Content-Type header in the request. If the MD5 checksum of the data written to the storage system does not match the optionally supplied ETag value, a 422 (Unprocessable Entity) status code is returned.

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Created	The request has been fulfilled.
202	Accepted	The request has been accepted for processing.
401	Unauthorized	Authentication has failed.
411	Length Required	The request did not specify the length of its content.
422	Unprocessable Entity	The request could not be followed due to semantic errors.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.
ETag	String	The MD5 checksum of your object’s data.
Content-Type	String	The media type of the entity-body sent. If not specified, the Content-Type is guessed, by using the Python mimetypes library, based on the object path.
Content-Length	Int	Set to the length of the object content. Do not set if chunked transfer encoding is being used.
Content-Disposition	String	The new browser behavior for the file, so that the downloader can save the file rather than displaying it using default browser settings.
Content-Encoding	String	The underlying media type of the compressed file.
Transfer-Encoding	String	Set to chunked to enable chunked transfer encoding. If used, do not set the Content-Length header to a non-zero value.
X-Delete-At	Int	The certain date, in the format of a Unix epoch timestamp, when the object will be removed.
X-Delete-After	Int	The certain date, in the format of a Unix epoch timestamp, after which the object will be removed.
X-Object-Meta-name	String	The custom object metadata. The name at the end of this header represents the name of your metadata.
X-Detect-Content-Type	Boolean	If you set this header to True, the Content-Type that is sent in the request (if any) is ignored, and Content-Type is guessed by using the Python mimetypes library based on the object path.
X-Object-Manifest	String	Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
X-Copy-From	String	If set, this is the name of an object used to create the new object by copying the X-Copy-From object. The value is in form container/object. You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using the PUT operation with X-Copy-From has the same effect as using the COPY operation to copy an object.
X-Copy-From-Account	String	Used for account to account copy. Specifies the account name from which you want to copy an object. (The account name is the last part of the storage URL).

This table shows the query parameters for the request:

Name	Type	Description
signature	String	Used with temporary URLs to sign the request. For more information about temporary URLs, see TempURL.
expires	String	Used with temporary URLs to specify the expiry time of the signature. For more information about temporary URLs, see TempURL.
multipart-	String	If you include the multipart-manifest=get query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the X-Object-Manifest response header for dynamic large objects or in the response body for static large objects.

This operation does not accept a request body.

Example: Create or update object HTTP request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 512000
X-Delete-At: 1339429105
Content-Disposition: attachment; filename=platmap.mp4
Content-Type: video/mp4
Content-Encoding: gzip
X-Object-Meta-PIN: 1234

Response

This table shows the header parameters for the response:

Name	Type	Description
Content-Length	String	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Etag	String	For objects smaller than 5 GB, this value is the MD5 checksum of the uploaded object content. The value is not quoted. If you supplied an ETag request header and the operation was successful, the values are the same. If you did not supply an ETag request header, check the ETag response header value against the object content you have just uploaded. For static large objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was uploaded. Also the value is enclosed in double- quotes. For dynamic large objects, the value is the MD5 checksum of the empty string.
Content-Type	String	The MIME type of the object.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.

This operation does not return a response body.

Example: Create or update object HTTP response

HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: 8a964ee2a5e88be344f36c22562a6486
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT

Delete object

DELETE /v1/{account}/{container}/{object}

This operation permanently deletes an object from the Cloud Files storage system. (You can use COPY and then DELETE to effectively move an object.)

Perform a DELETE operation on an object to permanently remove the object from the storage system (data and metadata).

Object deletion is processed immediately at the time of the request. Any subsequent GET, HEAD, POST, or DELETE operations return a 404 (Not Found) error unless object versioning is on and other versions exist. For more information about object versioning, see Object versioning.

Objects with the X-Delete-At or X-Delete-After header assigned are deleted within one day of the expiration time, and the object is not served immediately after the expiration time. For more details, see Expiring objects.

A status code of 204 (No Content) indicates success. Status code 404 (Not Found) is returned when the object does not exist.

For information about bulk deletions, see Bulk delete.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No Content	The request succeeded.
404	Not Found	The requested resource was not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.

This table shows the query parameters for the request:

Name	Type	Description
multipart-manifest	String	If you include the multipart-manifest=get query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the X-Object-Manifest response header for dynamic large objects or in the response body for static large objects.

This operation does not accept a request body.

Example: Delete object HTTP request

DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Response

This table shows the header parameters for the response:

Name	Type	Description
Content-Length	String	The length of the response body that contains the list of names. If the operation fails, this value is the length of the error text in the response body.
Content-Type	String	The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in the response body.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.

This operation does not return a response body.

Example: Delete object HTTP response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
Date: Wed, 15 Jan 2014 21:29:16 GMT

Copy object

COPY /v1/{account}/{container}/{object}

Using the Destination header, copies an existing object to another object with a new name in the Cloud Files storage system.

The new object can be in the same container, but have a different name from the original object. Or, the new object can have the same or a different name and be located in a different container than the original object.

Note

You can use a PUT operation with the X-Copy-From header to accomplish the same operation as the COPY operation. The PUT operation always creates a new object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object.

Suppose you upload a file with the wrong object name or content type, or you need to move some objects to another container. Without a server-side object copy feature, you would need to repeat uploading the same content and then delete the existing object. With a server-side object copy feature, you can save the step of re-uploading the content and thus also save the associated bandwidth charges, if any were to apply.

You can send a COPY request to the existing object and include the Destination header to specify the destination of the copy. The header value is the container and new object name in the form of /container/object. Unlike using the PUT request, this approach does not require a Content-Length header.

Example: Copy object approach 1 - using COPY

COPY /v1/account/sourceContainer/sourceObject  HTTP/1.1
Host: storageURL
X-Auth-Token: yourAuthToken
Destination: /destinationContainer/destinationObject

Alternatively, you can send a PUT request to the location of the new object (the destination), and add the X-Copy-From header to designate the source of the data. The header value must be the container and object name of the source object in the form of /container/object. The HTTP specification of a PUT request with the X-Copy-From header requires a Content-Length header, but the storage system does not use the Content-Length value to perform the operation. For this reason, you can simply send a Content-Length value of 0 (zero).

Note

By default, you cannot copy an object larger than 5 GB. For information about how to handle objects larger than 5 GB, see Creating large objects.

Example: Copy object approach 2 - using PUT

PUT /v1/account/destinationContainer/destinationObject  HTTP/1.1
Host: storageURL
X-Auth-Token: yourAuthToken
X-Copy-From: /sourceContainer/sourceObject
Content-Length: 0

With both of these approaches, the destination container must exist before you copy the object.

Note

If you are copying many objects, you can improve the total copy time by issuing several concurrent COPY commands. Because Cloud Files is a distributed storage system, your concurrent COPY commands run on separate machines simultaneously. As a best practice, you can run up to 100 concurrent COPY commands per container.

If you want to move the object rather than copy it, send a DELETE request to the source object after copying it. A move is simply a COPY operation followed by a DELETE operation.

All metadata is preserved during the object copy. Note that you can set metadata on the request to copy the object (with either PUT or COPY ), and the metadata overwrites any conflicting keys on the destination object.

Your account is not charged when you copy or move your objects within the same data center by using the internal network URI, ServiceNet, as the storage URL. You can find your ServiceNet endpoint in the service catalog that is created when you authenticate your session. For information about how to authenticate your session, see Authenticate to the Rackspace Cloud. As shown in the following partial service catalog example, the ServiceNet URI is listed as internalURL. The name is your Cloud Files storage URL with snet- prepended to it. If you do not know which data center you are working in, you can find it in the Cloud Control Panel. (For more information about service access endpoints, see Service access endpoints.)

Example: Data center endpoints

"endpoints": [
  {
    "region": "DFW",
    "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
    "tenantId": "MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
    "publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c"
  },
  {
    "region": "ORD",
    "internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c ",
    "tenantId": "MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c",
    "publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_9491081f-7e12-4f56-98d0-cdb3037c8d7c"
  }
 ]

This table shows the possible response codes for this operation:

Response Code	Name	Description
201	Created	The request has been fulfilled.
404	Not Found	The requested resource was not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.
X-Copy-From	String	Used with PUT, the container and object name of the source object in the form of /container/object.
X-Copy-From-Account	String	Specifies the account you are copying from.
Content-Length	Int (Required)	Used with PUT, the content length. Zero (0) is always acceptable for this operation.
Destination	String	Used with COPY, the container and object name of the destination object in the form of /container/object.
Destination-Account	String	Used for account to account copy. Specifies the destination account name (which is the last part of the storage URL).
Content-Type	String	The media type of the entity-body sent. If not specified, the Content-Type is guessed, by using the Python mimetypes library, based on the object path.
X-Detect-Content-Type	String	If you set this header to True, the Content-Type that is sent in the request (if any) is ignored, and Content-Type is guessed by using the Python mimetypes library based on the object path.
Content-Encoding	String	If set, the value of the Content-Encoding metadata.
Content-Disposition	String	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
X-Object-Meta-name	String	The container metadata, where name is the name of the metadata item. You must specify a X-Object-Meta-name header for each metadata item (for each name) that you want to add or update.

This operation does not accept a request body.

Example: Copy object using COPY HTTP request

COPY /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MySourceContainer/MySourceObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
Destination: /MyDestinationContainer/MyDestinationObject

Example: Copy object using PUT HTTP request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyDestinationContainer/MyDestinationObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
X-Copy-From: /MySourceContainer/MySourceObject
Content-Length: 0

Response

This table shows the header parameters for the response:

Name	Type	Description
Content-Length	String	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Etag	String	The MD5 checksum of the uploaded object content. The value is not quoted.
Content-Type	String	The MIME type of the object.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.
X-Copied-From-Last- Modified	String	For a copied object, shows the last modified date and time for the container and object name from which the new object was copied.
X-Copied-From	String	For a copied object, shows the container and object name from which the new object was copied. The value is in form container/object.
Last-Modified	String	The date and time that the object was created or the last time that the metadata was changed.
X-Object-Meta-name	String	The custom object metadata item, where name is the name of the metadata item. One X-Object-Meta-name response header appears for each metadata item (for each name).

This operation does not return a response body.

Example: Copy object using COPY HTTP response

HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: MySourceObject
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Test: testCF
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT

Example: Copy object using PUT HTTP response

HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: MySourceObject
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Test: testCF
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT

Show object metadata

HEAD /v1/{account}/{container}/{object}

This operation performs a HEAD operation on an object to retrieve object metadata and other standard HTTP headers.

Note

The HEAD return code for an object is different than the HEAD return code for a container. A HEAD request does not return a message body in the response, so a status code of 200 through 299 indicates success. When a HEAD request is performed against a container, it queries the container databases, and it does not retrieve the content from them. Thus, this operation returns the 204 (No Content) status code. However, when a HEAD request is performed against an object, it returns a 200 (OK) status code because it can view the content.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request has succeeded.
404	Not Found	The requested resource was not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.

This table shows the query parameters for the request:

Name	Type	Description
signature	String	Used with temporary URLs to sign the request. For more information about temporary URLs, see TempURL.
expires	String	Used with temporary URLs to specify the expiry time of the signature. For more information about temporary URLs, see TempURL.

This operation does not accept a request body.

Example: Get object metadata HTTP request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

Response

This table shows the header parameters for the response:

Name	Type	Description
X-Timestamp	String	An internal variable that indicates the last time an entity (account, container, or object) was modified. The format is the same as a Unix timestamp. The storage system uses this header to determine the latest version. For example, during replication, the storage system makes sure all three object replicas are up to date, and it uses the X- Timestamp header to determine which replica is the latest. You might notice that objects have both a Last-Modified and X-Timestamp header. The difference between these two headers is the resolution. Last- Modified has resolution up to one second, while X-Timestamp has resolution up to five decimal places of one second.
Last-Modified	String	An internal variable that indicates the last time an entity (account, container, or object) was modified. For Last- Modified, the time zone is UTC. You might notice that objects have both a Last-Modified and X- Timestamp header. The difference between these two headers is the resolution. Last- Modified has resolution up to one second, while X-Timestamp has resolution up to five decimal places of one second.
Content-Length	String	The length of the object content in the response body, in bytes.
Etag	String	The MD5 checksum of the uploaded object content. The value is not quoted.
Content-Type	String	The MIME type of the object.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.
Content-Encoding	String	If set, the value of the Content-Encoding metadata. If not set, this header is not returned by this operation.
Content-Disposition	String	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default. If not set, this header is not returned by this operation.
X-Delete-At	String	If set, the time when the object will be deleted by the system in the format of a UNIX epoch timestamp. If not set, this header is not returned by this operation.
X-Object-Manifest	String	If set, to this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form container/prefix.
X-Static-Large-Object	Boolean	Set to True if this object is a static large object manifest object.
X-Object-Meta-name	String	The custom object metadata item, where name is the name of the metadata item. One X-Object-Meta-name response header appears for each metadata item (for each name).

This operation does not return a response body.

Example: Get object metadata HTTP response

HTTP/1.1 200 OK
Date: Thu, 10 Jun 2010 20:59:39 GMT
Last-Modified: Fri, 11 Jun 2010 13:40:18 GMT
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 512000
Content-Type: text/plain; charset=UTF-8
X-Object-Meta-Meat: Bacon
X-Object-Meta-Fruit: Apple
X-Object-Meta-Veggie: Beans
X-Object-Meta-Dairy: Cheese

Create or update object metadata

POST /v1/{account}/{container}/{object}

This operation sets or updates your object metadata. Metadata must be in the format X-Object-Meta-name where name is the name of your metadata. You can also assign X-Delete-At or X-Delete-After to expiring objects.

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

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. For more information, see Delete container metadata.

This table shows the possible response codes for this operation:

Response Code	Name	Description
202	Accepted	The request was accepted for processing.
404	Not Found	The requested resource was not found.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{account}	String	Your unique account identifier.
{container}	String	The unique identifier of the container.
{object}	String	The unique identifier of the object.

This table shows the header parameters for the request:

Name	Type	Description
X-Auth-Token	String (Required)	Authentication token.
X-Object-Meta-name	String	The container metadata. The name represents the name of your metadata.
X-Delete-At	Int	The date, in the format of a Unix epoch timestamp, when the object will be removed.
X-Delete-After	Int	The date, in the format of a Unix epoch timestamp, after which the object is removed.
Content-Type	String	The media type of the entity-body sent. If not specified, the Content- Type is guessed, by using the Python mimetypes library, based on the object path.
X-Detect-Content-Type	String	If you set this header to True, the Content-Type that is sent in the request (if any) is ignored, and Content-Type is guessed by using the Python mimetypes library based on the object path.
Content-Disposition	String	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding	String	If set, the value of the Content-Encoding metadata.

This operation does not accept a request body.

Example: Update object metadata HTTP request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer/MyObject HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
X-Object-Meta-Fruit: Apple
X-Object-Meta-Veggie: Carrot

Response

This table shows the header parameters for the response:

Name	Type	Description
Content-Length	String	The length of the object content in the response body, in bytes.
Content-Type	String	The MIME type of the object.
X-Trans-Id	Uuid	A unique transaction identifier for this request.
Date	Datetime	The transaction date and time.

This operation does not return a response body.

Example: Update object metadata HTTP response

HTTP/1.1 202 Accepted
Date: Thu, 07 Jun 2007 20:59:39 GMT
Content-Length: 0
Content-Type: text/plain; charset=UTF-8
X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4