Container services operations#

You can perform the operations described in this section on containers in your Cloud Files account.

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

For your own requests, you must use your own account information, authentication token, and container 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.

Show container details and list objects#

GET /v1/{account}/{container}

This operation shows details for a specified container and lists objects, sorted by name, in the container. You can use optional query parameters to refine the list results.

A request with no query parameters returns the full list of object names stored in the container, up to 10,000 names. The response body shows the object names as one object name per line. Specifying the query parameters filters the full list and returns a subset of objects. For information about limiting and controlling the list, see Controlling a Large List of Objects.

An HTTP response status code of 200 through 299 indicates success. A status code of 200 (OK) is returned if there are objects, and a 204 (No Content) is returned if there are no objects. If the container does not exist, or if an incorrect account is specified, a status code 404 (Not Found) is returned.

Format Object List

If you append the format=xml or the format=json query parameter to the storage account URL, the service returns additional object information serialized in the specified format. The status codes are the same for format=xml and format=json. However, Content-Type matches the specified format. The example responses in this section are formatted for readability.

Controlling a Large List of Objects

A GET request against the container account URL returns a list of up to 10,000 objects. You can limit and control this list of results by using the marker, end_marker, and limit parameters.

The marker parameter tells Cloud Files where to begin your list of objects, and the end_marker parameter tells where to end the list. You can use them either independently or together, separated by an ampersand ( & ). If you do not specify them, your list displays up to 10,000 objects. Note that the marker and end_marker values must be URL-encoded before you send the HTTP request.

You can use the limit parameter to reduce the number of returned objects.

If the number of returned items equals the limit used (or 10,000 if no limit was specified), you can assume there are more object names.

As an example, use a listing of 5 object names, as follows:

gala
grannysmith
honeycrisp
jonagold
reddelicious

Use a limit of 2 to show how things work:

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

gala
grannysmith

Because the request returned two items, assume there are more object names to list and make another request with a marker of the last item returned:

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2 & marker=grannysmith
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

honeycrisp
jonagold

Again, two items are returned, and you assume that there might be more. So you make another GET request for two more:

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/AppleType?limit=2 & marker=jonagold
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

reddelicious

This one-item response shows fewer than the limit of two object names requested, and indicates that this is the end of the list.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

OK

The request succeeded.

204

No Content

The request succeeded. The server fulfilled the request but does not need to return a body.

404

Not Found

The requested resource was not found.

409

Conflict

The request could not be completed due to a conflict with the current state of the resource.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

Accept

String

Instead of using the format query parameter, set this header to application/json, application/xml, or text/xml.

This table shows the query parameters for the request:

Name

Type

Description

limit

Int

For an integer n, limits the number of results to n values.

marker

String

Given a string value x, returns object names greater in value than the specified marker.

end_marker

String

Given a string value x, returns object names lesser in value than the specified marker.

prefix

String

For a string value x, causes the results to be limited to object names beginning with the substring x.

format

String

Specifies either JSON or XML to return the respective serialized response.

delimiter

Char

For a character c, returns the object names nested in the container (without the need for the directory marker objects).

path

String

For a string x, returns the object names nested in the pseudo path. This parameter is equivalent to setting the delimiter parameter to / and the prefix to the path with a / on the end. For more information about pseudo paths, see the section on pseudo hierarchical folders and directories.

This operation does not accept a request body.

Example: Show container details and list objects XML request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=xml HTTP/1.1
Host: storage.clouddrive.com
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example: Show container details and list objects JSON request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer?
format=json HTTP/1.1
Host: storage.clouddrive.com
X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

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.

X-Container-Object-Count

Int

The number of objects.

Accept-Ranges

String

The type of ranges that the object accepts.

X-Container-Bytes-Used

Int

The count of bytes used in total.

X-Container-Meta-name

String

The custom container metadata item, where name is the name of the metadata item. One X-Container- Meta-name response header appears for each metadata item (for each name).

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.

Example: Show container details and list objects XML response

HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/xml; charset=utf-8
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT

<?xml version="1.0" encoding="UTF-8"?>
<container name="marktwain">
    <object>
        <name>goodbye</name>
        <hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
        <bytes>14</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:41:49.390270</last_modified>
    </object>
    <object>
        <name>helloworld</name>
        <hash>ed076287532e86365e841e92bfc50d8c</hash>
        <bytes>12</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:37:43.427570</last_modified>
    </object>
</container>

Example: Show container details and list objects JSON response

HTTP/1.1 200 OK
Content-Length: 341
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT

[
 {
 "hash":"451e372e48e0f6b1114fa0724aa79fa1",
 "last_modified":"2014-01-15T16:41:49.390270",
 "bytes":14,
 "name":"goodbye",
 "content_type":"application/octet-stream"
 },
 {
 "hash":"ed076287532e86365e841e92bfc50d8c",
 "last_modified":"2014-01-15T16:37:43.427570",
 "bytes":12,
 "name":"helloworld",
 "content_type":"application/octet-stream"
 }
]

Create container#

PUT /v1/{account}/{container}

This operation creates a Cloud Files container. Containers are storage compartments for your data. The URL-encoded name must be no more than 256 bytes and cannot contain a forward slash character (/). You can create up to 500,000 containers in your Cloud Files account.

You can assign custom metadata for containers by including additional HTTP headers with an X-Container-Meta- prefix on the POST request. For details on setting custom metadata, see Create or update account metadata.

Using custom container metadata, you can create information in the header to effectively tag a container. The container metadata restrictions are the same as the restrictions for object metadata. You can have a maximum of 4096 bytes of metadata for the container, with a maximum of 90 distinct metadata items. Each distinct metadata item can have a name length of up to 128 characters with a maximum of 256 bytes in the value. Any valid UTF-8 encoded string value is allowed for metadata. In addition for custom metadata, we recommend that you URL-encode any non-ASCII values by using a % symbol followed by the two-digit hexadecimal ISO-Latin code for the character.

A status code of 201 (Created) indicates that the container was created as requested. Container PUT requests are idempotent, and a code of 202 (Accepted) is returned if the container existed prior to the request. If you make a PUT request to a container with an X-Container-Meta- prefix in the header, your GET or HEAD request responses carry the metadata prefix from the container in subsequent requests.

This table shows the possible response codes for this operation:

Response Code

Name

Description

201 or 202

Created or Accepted

The request has been fulfilled. For 201 Created, the new container has been created. For 202 Accepted, the request has been accepted for processing.

400

Bad Request

The request could not be understood by the server due to malformed syntax.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

X-Container-Meta-name

String

Custom container metadata. Replace name at the end of the header with the name for your metadata.

X-Container-Read

String

Sets an access control list (ACL) that grants read access. This header can contain a comma- delimited list of users that can read the container (allows the GET method for all objects in the container).

X-Container-Write

String

Sets an ACL that grants write access. This header can contain a comma-delimited list of users that can write to the container (allows PUT, POST, COPY, and DELETE methods for all objects in the container).

X-Versions-Location

String

Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.

This operation does not accept a request body.

Example: Create container HTTP request

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

Example: Create container with metadata HTTP request

PUT /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
X-Container-Meta-InspectedBy: JackWolf

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: Create container HTTP response

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
Date: Tue, 14 Jan 2014 19:09:10 GMT

Example: Create container with metadata HTTP response

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT

Delete container#

DELETE /v1/{account}/{container}

This operation deletes an empty container.

A DELETE operation against a storage container permanently removes it. The container must be empty before it can be deleted.

Before using DELETE, you can use a GET operation against the container to list any objects that it contains. (See Show container details and list objects.)

A status code of 204 (No Content) indicates success. A status code of 404 (Not Found) is returned if the requested container is not found. A status code of 409 (Conflict) is returned if the container is not empty.

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.

409

Conflict

The request could not be completed due to a conflict with the current state of the resource.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

This operation does not accept a request body.

Example: Delete container HTTP request

DELETE /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer 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 container HTTP response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
Date: Thu, 16 Jan 2014 18:04:04 GMT

Create or update container metadata#

POST /v1/{account}/{container}

This operation creates or updates the container metadata by associating custom metadata headers with the container-level URI. These headers must have the format X-Container-Meta-name.

To set or edit container metadata, perform a POST operation to the container. The operation must include X-Container-Meta-name, where name is the name of your custom metadata. Subsequent POST operations to the h eader using the same metadata name overwrite the previous value.

To view your metadata changes, perform a HEAD operation on the container. (For more information, see Show container metadata.) Do not try to send the metadata in your HEAD request.

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 Create or update container metadata.

Note that updating and deleting object metadata works differently. For an example, see Additional container services information.

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

Note

See the following information about adding metadata:

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

X-Container-Meta-name

String (Required)

The container metadata. Replace name at the end of the header with the name of your metadata.

X-Container-Read

String

Sets an access control list (ACL) that grants read access. This header can contain a comma- delimited list of users that can read the container (allows the GET method for all objects in the container).

X-Container-Write

String

Sets an ACL that grants write access. This header can contain a comma-delimited list of users that can write to the container (allows PUT, POST, COPY, and DELETE methods for all objects in the container).

X-Remove-Container-name

String

Removes the metadata item named metadata. For example, X-Remove- Container-Read removes the X-Container-Read metadata item.

X-Versions-Location

String

Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.

X-Remove-Versions- Location

String

Set to any value to disable versioning.

Content-Type

String

Changes the MIME type for the object.

X-Detect-Content-Type

Boolean

If set to True, Cloud Files guesses the content type based on the file extension and ignores the value sent in the Content-Type header, if present.

This operation does not accept a request body.

Example: Create or update container metadata HTTP request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/
1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
X-Container-Meta-Book: MobyDick
X-Container-Meta-Subject: Whaling

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: Create or update container metadata HTTP response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx05dbd434c651429193139-0052d82635
Date: Thu, 16 Jan 2014 18:34:29 GMT

Show container metadata#

HEAD /v1/{account}/{container}

This operation shows container metadata, including the number of objects in the container and the total bytes for all objects stored in the container.

The HEAD operation against the container returns the following metadata:

  • How many objects are in the container ( X-Container-Object-Count )

  • The total bytes for all objects stored in the container ( X-Container-Bytes-Used )

  • Any custom metadata that is set on the container ( X-Container-Meta-name )

To set and edit your custom metadata, see Create or update container metadata.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

This operation does not accept a request body.

Example: Get container metadata HTTP request

HEAD /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer 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-Container-Object-Count

Int

The number of objects in the container.

X-Container-Bytes-Used

Int

The total number of bytes used for all objects in the container.

X-Container-Meta-name

String

Any metadata set on the container. The name at the end of the header is the name of your metadata. One X- Container-Meta-name response header appears for each metadata item (for each name).

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.

X-Container-Read

String

The access control list (ACL) that grants read access. If not set, this header is not returned by this operation. This header can contain a comma-delimited list of users that can read the container (allows the GET method for all objects in the container).

X-Container-Write

String

The ACL that grants write access. If not set, this header is not returned by this operation. This header can contain a comma- delimited list of users that can write to the container (allows PUT, POST, COPY, and DELETE methods for all objects in the container).

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.

Accept-Ranges

String

The type of ranges accepted.

X-Versions-Location

String

Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.

This operation does not return a response body.

Example: Get container metadata HTTP response

HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Meta-Author: SamuelClemens
X-Container-Bytes-Used: 14
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
Date: Thu, 16 Jan 2014 18:37:22 GMT

Delete container metadata#

POST /v1/{account}/{container}

This operation deletes container metadata.

To delete a metadata header, use a POST operation. You send the POST operation 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.

To set and edit your custom metadata, see Create or update container metadata.

Note that updating and deleting object metadata works differently. For an example, see Create or update object metadata.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

X-Remove-Container-Meta- name

String (Required)

The metadata to be deleted. Replace name at the end of the header with the name for your metadata.

X-Container-Read

String

The access control list (ACL) that grants read access. If not set, this header is not returned by this operation. This header can contain a comma-delimited list of users that can read the container (allows the GET method for all objects in the container).

X-Container-Write

String

The ACL that grants write access. If not set, this header is not returned by this operation. This header can contain a comma- delimited list of users that can write to the container (allows PUT, POST, COPY, and DELETE methods for all objects in the container).

This operation does not accept a request body.

Example: Delete container metadata HTTP request

POST /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123/MyContainer HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c
X-Remove-Container-Meta-Subject: x

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 container metadata HTTP response

HTTP/1.1 204 No Content
Date: Thu, 09 Jan 2014 22:28:22 GMT
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe749a717ee5e4da7a6895-0052cf2286dfw1