Listing containers

You use the HTTP GET method to list the containers in an account. You need an account to request this operation.

The target of a request to list the container is a tenant (that is, the service point). The list of containers in the response contains only containers created in the context of that tenant and lists all containers with HSwift API enabled. The containers are listed in alphanumeric order.

The list of containers is returned in a plain text response body, although it can be configured to be returned in XML or JSON response bodies.

You use query parameters to limit the items included in a container listing.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to list the containers you own has this format:

  • With the Keystone tenant ID:
    GET /swift/v1/tenant-ID HTTP/1.1
  • With the account name:
    GET /swift/v1/account-name HTTP/1.1

Request headers

The table below describes the headers you can use in a request to list the containers you own.

NameTypeDescription
AcceptStringSet this header to application/json, application/xml, or text/xml. The response body will be serialized in the specified format.
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"

Response headers

The table below describes the response headers returned in response to a successful request to list the containers you own.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
X-Account-Bytes-UsedInt (Required)This number is the total amount of bytes stored in object storage by this account. The number includes to total amount of bytes across all objects in all containers on the account.
X-Account-Container-CountInt (Required)

The number of containers on the account.

This number is limited to the total number of namespaces that an HCP tenant may have which is 10,000.

X-Account-Object-CountInt (Required)This number is the total amount of objects that the account has across all of its containers.
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.

Response body

By default, HCP returns the list of containers you own in a plain text format. For the purpose of this example, the response body have been converted to XML using the Accept header. This is the response body, in XML format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<account name="europe">
     <container>
         <name>finance</name>
         <bytes>8192</bytes>
         <count>1</count>
     </container>
     <container>
         <name>human-resources</name>
         <bytes>0</bytes>
         <count>0</count>
     </container>
</account>

The list below describes the XML elements in this response body. The elements are listed in alphabetical order.

  • Account name

    Root element

  • Bytes

    Child of the Container element.

    The Bytes element specifies the size, in bytes, of the content of the item.

    The response body includes Size elements for the listed directories. However, because directories have no content, the value of this element for a directory is always 0 (zero).

  • Count

    Child of the Container element.

    The Count element specifies the number of directories inside the Container element.

  • Container

    Child of the Account name element and container for the Name, Bytes, and Count elements.

    The response body contains one Container element for each container you own.

  • Name

    Child of the Container element.

    The Name element specifies the name of a Container.

HTTP response codes

The table below describes HTTP status codes that can be returned in response to a request to list the containers you own.

CodeMeaningDescription
200SuccessThe response body has listed the containers on the account.
204Success

This code applies only to the Plain Text Response.

The response body shows no containers. Either the account has no containers or you are paging through a long list of names by using the marker, limit, or end_marker query parameters, and you have reached the end of the list.

500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

If this error persists, contact your tenant administrator.

Example: Listing containers

Here's a sample GET request that returns a list of the containers in the context of the europe tenant.

Request with curl command line

curl -X GET http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e -H "Accept: application/xml" -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
Accept: application/XML

Response headers with containers

HTTP/1.1 200 OK
Date: Fri, 17 Jan 2014 16:03:23 GMT
X-Trans-Id: 28b610b7-0fbc-4d83-821b-f7d2a3f20e27
Content-Type: application/xml;charset=UTF-8
X-Account-Object-Count: 1
X-Account-Container-Count: 2
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
Content-Length: 0

Response body with containers

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<account name="europe">
     <container>
          <name>finance</name>
          <bytes>8192</bytes>
          <count>1</count>
     </container>
     <container>
          <name>human-resources</name>
          <bytes>0</bytes>
          <count>0</count>
     </container>
</account>