Object Operations

An object is a container for storing data and metadata. A container may have many objects, but the object names must be unique. This API enables a client to create an object, set access controls and metadata, retrieve an object’s data and metadata, and delete an object. Since this API makes requests related to information in a particular user’s account, all requests in this API must be authenticated unless the container or object’s access control is deliberately made publicly accessible (i.e., allows anonymous requests).

Create/Update an Object

To create a new object, make a PUT request with the API version, account, container name and the name of the new object. You must have write permission on the container to create or update an object. The object name must be unique within the container. The PUT request is not idempotent, so if you do not use a unique name, the request will update the object. However, you may use pseudo-hierarchical syntax in your object name to distinguish it from another object of the same name if it is under a different pseudo-hierarchical directory. You may include access control headers and metadata headers in the request.

Syntax

PUT /{api version}/{account}/{container}/{object} HTTP/1.1
     Host: {fqdn}
     X-Auth-Token: {auth-token}

Request Headers

ETag

Description

An MD5 hash of the object’s contents. Recommended.

Type

String

Required

No

Content-Type

Description

The type of content the object contains.

Type

String

Required

No

Transfer-Encoding

Description

Indicates whether the object is part of a larger aggregate object.

Type

String

Valid Values

chunked

Required

No

Copy an Object

Copying an object allows you to make a server-side copy of an object, so that you don’t have to download it and upload it under another container/name. To copy the contents of one object to another object, you may make either a PUT request or a COPY request with the API version, account, and the container name. For a PUT request, use the destination container and object name in the request, and the source container and object in the request header. For a Copy request, use the source container and object in the request, and the destination container and object in the request header. You must have write permission on the container to copy an object. The destination object name must be unique within the container. The request is not idempotent, so if you do not use a unique name, the request will update the destination object. However, you may use pseudo-hierarchical syntax in your object name to distinguish the destination object from the source object of the same name if it is under a different pseudo-hierarchical directory. You may include access control headers and metadata headers in the request.

Syntax

PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1
X-Copy-From: {source-container}/{source-object}
Host: {fqdn}
X-Auth-Token: {auth-token}

or alternatively:

COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1
Destination: {dest-container}/{dest-object}

Request Headers

X-Copy-From

Description

Used with a PUT request to define the source container/object path.

Type

String

Required

Yes, if using PUT

Destination

Description

Used with a COPY request to define the destination container/object path.

Type

String

Required

Yes, if using COPY

If-Modified-Since

Description

Only copies if modified since the date/time of the source object’s last_modified attribute.

Type

Date

Required

No

If-Unmodified-Since

Description

Only copies if not modified since the date/time of the source object’s last_modified attribute.

Type

Date

Required

No

Copy-If-Match

Description

Copies only if the ETag in the request matches the source object’s ETag.

Type

ETag.

Required

No

Copy-If-None-Match

Description

Copies only if the ETag in the request does not match the source object’s ETag.

Type

ETag.

Required

No

Delete an Object

To delete an object, make a DELETE request with the API version, account, container and object name. You must have write permissions on the container to delete an object within it. Once you have successfully deleted the object, you will be able to reuse the object name.

Syntax

DELETE /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}

Get an Object

To retrieve an object, make a GET request with the API version, account, container and object name. You must have read permissions on the container to retrieve an object within it.

Syntax

GET /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}

Request Headers

range

Description

To retrieve a subset of an object’s contents, you may specify a byte range.

Type

Date

Required

No

If-Modified-Since

Description

Only copies if modified since the date/time of the source object’s last_modified attribute.

Type

Date

Required

No

If-Unmodified-Since

Description

Only copies if not modified since the date/time of the source object’s last_modified attribute.

Type

Date

Required

No

Copy-If-Match

Description

Copies only if the ETag in the request matches the source object’s ETag.

Type

ETag.

Required

No

Copy-If-None-Match

Description

Copies only if the ETag in the request does not match the source object’s ETag.

Type

ETag.

Required

No

Response Headers

Content-Range

Description

The range of the subset of object contents. Returned only if the range header field was specified in the request

Get Object Metadata

To retrieve an object’s metadata, make a HEAD request with the API version, account, container and object name. You must have read permissions on the container to retrieve metadata from an object within the container. This request returns the same header information as the request for the object itself, but it does not return the object’s data.

Syntax

HEAD /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}

Add/Update Object Metadata

To add metadata to an object, make a POST request with the API version, account, container and object name. You must have write permissions on the parent container to add or update metadata.

Syntax

POST /{api version}/{account}/{container}/{object} HTTP/1.1
Host: {fqdn}
X-Auth-Token: {auth-token}

Request Headers

X-Object-Meta-{key}

Description

A user-defined meta data key that takes an arbitrary string value.

Type

String

Required

No