Account services operations#

You can perform the operations in the following table at the account level of 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

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

GET /v1/{account}

This operation lists the storage containers in your account and sorts them by name. You perform the operation against your storage account URL.

The list is limited to 10,000 containers at a time. For information on limiting and navigating the list, see the following section, Controlling a Large List of Containers.

Container names are sorted based on a binary comparison, a built-in collating function that compares string data by using SQLite’s memcmp() function, regardless of text encoding. For more information, see Collating Sequences.

A list of containers is returned in the response body, one container per line.

The character sequence used to create the newline that separates the container names is a single n. If you want to parse these listings, you send an Accept: application/json or Accept: application/xml header with the request to get the results in JSON or XML.

An HTTP response status code of 200 through 299 indicates success. A 200 (OK) code is returned if there are containers, and a 204 (No Content) code is returned if there are no containers.

Format Container List

If you append the ?format=xml or ?format=json query parameter to the storage account URL, the service returns container information serialized in the specified format. To format your results, you must place this query parameter before any other parameters.

The example responses in this section are formatted for readability.

Controlling a Large List of Containers

A GET operation on the storage account URL returns a list of up to 10,000 container names. You can control and limit this list of results by using the marker, end_marker, and limit parameters. These parameters provide a mechanism for iterating through the entire list of containers.

The marker parameter tells Cloud Files where to begin your list of containers, and the end_marker parameter specifies where to end the list. You can use them independently or together, separated by an ampersand ( & ). If you do not specify them, your list displays up to 10,000 containers. 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.

Note

At this time, a prefix query parameter is not supported at the account level.

As an example, start with an account that has five container names, as follows:

apples
bananas
kiwis
oranges
pears

Use a limit of 2 to show how things work:

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

apples
bananas

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

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

kiwis
oranges

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?limit=2 & marker=oranges
Host: storage.clouddrive.com
X-Auth-Token: f064c46a782c444cb4ba4b6434288f7c

pears

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

By using the end_marker parameter, you can limit the result set to container names less than the given value.

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

apples
bananas
kiwis

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.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

Your unique account identifier.

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 value n, limits the number of results to n values.

marker

String

Given a string value x, returns container names greater in value than the specified marker. Only strings using UTF-8 encoding are valid.

end_marker

String

Given a string value x, returns container names lesser in value than the specified marker. Only strings using UTF-8 encoding are valid.

format

String

Value of the serialized response format, either JSON or XML.

prefix

String

Prefix value. Object names in the response begin with this value.

delimiter

Char

Delimiter value, which returns the object names that are nested in the container.

This operation does not accept a request body.

Example: Show account details and list containers XML request

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

Example: Show account details and list containers JSON request

GET /v1/MossoCloudFS_0672d7fa-9f85-4a81-a3ab-adb66a880123?format=json 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-Account-Object-Count

Int

The number of objects in the account.

X-Account-Bytes-Used

Int

The total number of bytes that are stored in Cloud Files for the account.

X-Account-Container-Count

Int

The number of containers.

X-Account-Meta-name

String

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

X-Account-Meta-Temp-URL- Key

String

The secret key value for temporary URLs. If not set, this header is not returned by this operation.

X-Account-Meta-Temp-URL- Key-2

String

A second secret key value for temporary URLs. If not set, this header is not returned by this operation.

X-Trans-Id

Uuid

A unique transaction identifier for this request.

Date

Datetime

The transaction date and time.

Example: Show account details and list containers XML response

HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT

<?xml version="1.0" encoding="UTF-8"?>
<account name="my_account">
    <container>
        <name>janeausten</name>
        <count>0</count>
        <bytes>0</bytes>
    </container>
    <container>
        <name>marktwain</name>
        <count>1</count>
        <bytes>14</bytes>
    </container>
</account>

Example: Show account details and list containers JSON response

HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT

[
   {
     "count": 0,
     "bytes": 0,
     "name": "janeausten"
   },
   {
     "count": 1,
     "bytes": 14,
     "name": "marktwain"
   }
]

Create or update account metadata#

POST /v1/{account}

This operation creates or updates account metadata.

You can associate custom metadata headers with the account level URI. To create or update an account metadata header, submit a POST operation. These headers must have the format X-Account-Meta-name. Replace name with name of your metadata. (In the following example request, the metadata headers are X-Account-Meta-Book and X-Account-Meta-Subject.)

Subsequent POST operations for the same key/value pair overwrite the previous value.

To confirm your metadata changes, you can perform a HEAD operation on the account. (For information, see Get account metadata.) Do not send the metadata in your HEAD operation.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No Content

The request succeeded.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

X-Account-Meta-Temp-URL- Key

String

The secret key value for temporary URLs.

X-Account-Meta-Temp-URL- Key-2

String

A second secret key value for temporary URLs. The second key enables you to rotate keys by having an old and new key active at the same time.

X-Account-Meta-name

String (Required)

Account metadata that you want to create or update. Replace name at the end of the header with the name for your metadata. You must specify a X-Account-Meta-name header for metadata item (for each name) that you want to add or update.

This operation does not accept a request body.

Example: Create or update account metadata HTTP request

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

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.

Content-Type

String

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

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

Get account metadata#

HEAD /v1/{account}

This operation performs a HEAD operation on your storage account URL to get the following information:

  • The number of containers that you have in your account ( X-Account-Container-Count )

  • The number of objects that are stored in the containers in your account ( X-Account-Object-Count )

  • The total bytes that are stored for your account ( X-Account-Bytes-Used )

An HTTP status code of 200 through 299 indicates success. In the example, a 204 (No Content) status code is returned. A 401 (Unauthorized) status code is returned for an invalid account or authentication token.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No Content

The request succeeded.

401

Unauthorized

Authentication has failed.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

Your unique account identifier.

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 account metadata HTTP request

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

Int

The total number of objects that are stored in Cloud Files for the account.

X-Account-Bytes-Used

Int

The total number of bytes that are stored in Cloud Files for the account.

X-Account-Container-Count

Int

The total number of containers that are stored in the Cloud Files for the account.

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.

Content-Type

String

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-Account-Meta-name

String

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

X-Account-Meta-Temp-URL- Key

String

The secret key value for temporary URLs. If not set, this header is not returned by this operation.

X-Account-Meta-Temp-URL- Key-2

String

A second secret key value for temporary URLs. If not set, this header is not returned by this operation.

Example: Get account metadata HTTP response

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 573
X-Timestamp: 1369081921.78518
X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284e
X-Account-Bytes-Used: 14268918
X-Account-Container-Count: 1
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx8e82a77399724e40a90e8-0052cf0e52dfw1
Date: Thu, 09 Jan 2014 21:02:10 GMT

Delete account metadata#

POST /v1/{account}

This operation deletes account metadata.

To delete a metadata header, use the POST operation to send an empty value for that particular header.

If the tool that you use to communicate with Cloud Files does not support empty headers, such as an older version of cURL, send the X-Remove-Account-Meta-name: arbitrary value header. The arbitrary value is ignored. In the following example request, X-Remove-Account-Meta-Book: x is used.

This table shows the possible response codes for this operation:

Response Code

Name

Description

204

No Content

The request succeeded.

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.

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String (Required)

Authentication token.

X-Account-Meta-Temp-URL- Key

String

The secret key value for temporary URLs.

X-Account-Meta-Temp-URL- Key-2

String

A second secret key value for temporary URLs. The second key enables you to rotate keys by having an old and new key active at the same time.

X-Remove-Account-Meta- name

String (Required)

Header to send to delete account metadata. Replace name at the end of the header with the name for your metadata.

This operation does not accept a request body.

Example: Delete account metadata HTTP request

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

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.

Content-Type

String

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

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