Skip to main content
Hitachi Vantara Knowledge

Working with containers

For each container operation you can request, this chapter:

  • Describes the operation
  • Shows the request line for the operation
  • Describes the request headers for the operation
  • Describes the response headers returned for a successful execution of the requested operation
  • Shows the format of the request or response body where applicable
  • Explains the HTTP status codes that can be returned in response to requests for the operation
  • Presents one or more examples of requests for the operation
NoteTo perform these container activities, the management API must be enabled for the owning tenant:
  • Create a container
  • List the containers you own
  • Add or remove an ACL for a container
  • Delete a container

If you cannot perform these activities, contact your tenant administrator.

Creating a container

You use the HTTP PUT method to create a container. You can create a container only if your HSwift account is configured to let you do so.

When you create a container, you specify a name for it. If you use the PUT method to add an another container with a name that is identical to a container that already exists, you overwrite the metadata of the current container.

You can specify an ACL for a container in the same request as you use to create the container. To do this, you need to use ACL headers.

If the ACL you specify in a request to create a container is invalid, HCP returns a 400 (Bad Request) status code and does not create the container.

When you create a container, you get browse, read, and write data access permissions for the container.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to create a container has either of these formats:

  • With the Keystone tenant ID:
    PUT /swift/v1/tenant-ID/container-name HTTP/1.1
  • With the account name:
    PUT /swift/v1/account-name/container-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to create a container.

NameTypeDescription
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"
X-Container-Meta-Quota-BytesStringSets a limit on the size, in bytes, of objects that can be stored in the container. Once you set this quota it cannot be removed, only changed.
X-Container-ReadString

Adds Read, Browse or both data access permissions to the container.

This header can be used to grant permissions to individual Keystone users or make the container public.

X-Container-WriteString

Adds Write, Delete or both data access permissions to the container.

This header can be used to permissions to individual Keystone users or make the container public.

Response headers

The table below describes the response headers returned in response to a successful request to create a container.

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-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP response codes

The table below describes HTTP status codes that can be returned in response to a request to create a container.

CodeMeaningDescription
201CreatedThe container is created.
202AcceptedThe container already exists.
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: Creating a container

Here's a sample PUT request that creates a container named finance in the context of the tenant named europe.

Request with cURL command line

curl -X PUT http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance -i -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 201 Created
Date: Fri, 31 Oct 2014 12:45:01 GMT
Content-Length: 0
X-Trans-Id: tx78cf0d46829f49529ed1a-0053fccad0
Example: Creating a container with an ACL (data permission only)

Here's a sample PUT request that creates a container named human-resources and adds an ACL to the container. The ACL grants read permission to all users and write permission to the Keystone users with usernames mwhite and pdgrey.

Request with cURL command line

curl -X PUT http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/human-resources -i -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "X-Container-Read: *" -H "X-Container-Write: mwhite, pdgrey"

Request headers

PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 202 Created
Date: Fri, 31 Oct 2014 12:48:13 GMT
Content-Length: 0
X-Trans-Id: tx78cf0d46829f49529ed1a-0053fccad0

Listing account metadata

You use the HTTP HEAD method to list account metadata. You need an account to request this operation.

The target of a request to list the account metadata is a tenant (that is, the service point). When you list account metadata, you are returned information about the total number of containers on that account, the number of objects in the account, and the total amount of bytes used.

The total number of containers is calculated in the context of that tenant and even incorporates containers that don't have the HSwift API enabled. The object count is calculated in the same manner.

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 account containers has either of these formats:

  • With the Keystone tenant ID:
    HEAD /swift/v1/tenant-ID HTTP/1.1
  • With the account name:
    HEAD /swift/v1/account-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to list account container data.

NameTypeDescription
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 account container data.

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.
HTTP response codes

The table below describes HTTP status codes that can be returned in response to a request to list account container data.

CodeMeaningDescription
204SuccessIf the request succeeds, the operation returns this code.
401UnauthorizedIf you do not have the permissions to view the account's container data.
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 an account's metadata

Here's a sample HEAD request that lists the metadata of an account named europe.

Request with curl command line

curl -i -X HEAD http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

HEAD /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 204 No Content
Date: Fri, 31 Oct 2014 12:53:19 GMT
X-Trans-Id: 47b950a0-2e0d-4c25-86a3-fbd709b55a08
X-Account-Object-Count: 7
X-Account-Container-Count: 2
X-Account-Bytes-Used: 349
Content-Length: 0

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>

Checking a container's metadata

You use the HTTP HEAD method to check a container's metadata. To successfully check a container's metadata, you need read permission for the container.

If the container you specify in the HEAD request does not exist, HCP returns a 404 (Not Found) status code. If you do not have read permission for the container, HCP returns a 403 (Forbidden) status code.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to check a container's metadata has either of these formats:

  • With the Keystone tenant ID:
    HEAD /swift/v1/tenant-ID/container-name HTTP/1.1
  • With the account name:
    HEAD /swift/v1/account-name/container-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to check a container's metadata.

NameTypeDescription
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 check a container's metadata.

NameTypeDescription
Accept-RangesString (Required)Always bytes. This header shows the type of ranges that an object accepts from a Range request header.
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-Container-Bytes-UsedInt (Required)The total amount of bytes of data stored in the container. This number is capped by the X-Container-Meta-Quota-Bytes header.
X-Container-Meta-Quota-BytesStringIf a quota has been set on the amount of bytes that can be stored by this container, this header returns the size, in bytes, of objects that can be stored in the container.
X-Container-Object-CountInt (Required)The total number of objects stored in the container. This number includes all objects in all directories that are in the container. Directories are not included in this number.
X-Container-ReadString

Lists the Read and Browse permissions existing on the container.

This header can either list individual Keystone users with the Read permissions or mark the container as public.

X-Container-WriteString

Lists the Write ACL permissions existing on the container.

This header can either list individual Keystone users with Write permissions or mark the container as public.

X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to check a container's metadata.

CodeMeaningDescription
204No ContentNo Response Body.
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: Checking a container's metadata

Here's a sample HEAD request that checks the metadata of a container named finance.

Request with curl command line

curl -i -X HEAD http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

HEAD /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 204 No Content
Date: Fri, 31 Oct 2014 13:07:45 GMT
X-Trans-Id: 3c74e66d-9fb7-407d-9762-391d3e77014f
X-Container-Object-Count: 1
X-Container-Bytes-Used: 0
X-Container-Meta-Quota-Bytes: 10737418240
X-Container-Read:
X-Container-Write: *
Accept-Ranges: bytes
Content-Length: 0

Adding an ACL to a container

You use the HTTP POST method with either the read or write ACL header to add an ACL to an existing container. Adding an ACL to a container replaces the existing read or write ACL in its entirety. You cannot modify an existing ACL in place.

To add an ACL to a container, you need write ACL permission for the container.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to add an ACL (write or read) to a container has either of these formats:

  • With the Keystone tenant ID:
    POST /swift/v1/tenant-ID/container-name HTTP/1.1
    "X-Container-Write: acl-permitted-account-name"

    or

    POST /swift/v1/tenant-ID/container-name HTTP/1.1
    "X-Container-Read: acl-permitted-account-name"
  • With the account name:
    POST /swift/v1/account-name/container-name HTTP/1.1
    "X-Container-Write: acl-permitted-account-name"

    or

    POST /swift/v1/account-name/container-name HTTP/1.1
    "X-Container-Read: acl-permitted-account-name"
Request headers

The table below describes the headers you can use in a request to add an ACL container.

NameTypeDescription
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"
X-Container-ReadString

Adds a Read, Browse or both access permissions to the container.

This header can be used to add permissions to individual Keystone users or make the container public.

In order to make a container public, enter an asterisk (*) as the request header's value.

X-Container-WriteString

Adds Write, Delete or both access permissions to the container.

This header can be used to add permissions to individual Keystone users or make the container public.

In order to make a container public, enter an asterisk (*) as the request header's value.

X-Remove-Container-nameString

This header removes other headers supported by the POST command. Instead of replacing the data with new information, this header acts as a delete for other headers.

Here is an example of how to use the header. If you want to get rid of all your X-Container-Write ACL permissions on a container you format the X-Remove-Container-name header like this:

X-Remove-Container-Write

When you execute this example operation all write ACLs are removed from the container.

Response headers

The table below describes the response headers returned in response to a successful request to add an ACL to a container.

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-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes the response headers returned in response to a successful request to add an ACL to a container.

CodeMeaningDescription
204No contentThe POST was successful.
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: Adding an ACL to a container by specifying individual users

Here's a sample POST request that adds an ACL to the finance container by using the X-Container-Write and X-Container-Read headers. The ACL grants write permission to the Keystone authenticated user pdgrey, and read permissions to Keystone authenticated users pdgrey and mwhite.

Request with curl command line

curl -i -X POST http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "X-Container-Write: pdgrey" -H "X-Container-Read: pdgrey, mwhite"

Request headers

POST /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
X-Container-Write: pdgrey
X-Container-Read: pdgrey, mwhite

Response headers

HTTP/1.1 204 No Content
Date: Fri, 31 Oct 2014 13:07:45 GMT
X-Trans-Id: 3c74e66d-9fb7-407d-9762-391d3e77014f
Content-Length: 0
Content-Type: application/octet-stream
Example: Adding a public ACL to a container

Here's a sample POST request that adds an ACL that give public read, browse, write, and delete data permissions to the finance container by using the X-Container-Write and X-Container-Read headers.

Request with curl command line

curl -i -X POST http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "X-Container-Write: *" -H "X-Container-Read: *"

Request headers

POST /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
X-Container-Write: *
X-Container-Read: *

Response headers

HTTP/1.1 204 No Content
Date: Fri, 31 Oct 2014 13:07:45 GMT
X-Trans-Id: 3c74e66d-9fb7-407d-9762-391d3e77014f
Content-Length: 0
Content-Type: application/octet-stream

Listing container contents

You use the HTTP GET method to list the contents of a container and its ACLs. To list the contents of a container, you need browse permission for the container.

For the purpose of a container listing, the container contents consist not only of the objects you stored in the container but also of the directories that you created in the container or that HCP created automatically from the object names. For example, by default, if a container contains an object named quarterly_rpts/Q4_2012, a list of the container contents includes these two items:

quarterly_rpts/
quarterly_rpts/Q4_2012

By default, a container listing includes only the current (or only) versions of objects. You cannot request to view older versions of objects using HSwift.

You can use query parameters to list only a subset of the items in a container.

A container listing is returned in a plain text response body although the format can be changed to either an XML or JSON response body. In the response body, items in the container listing occur in alphanumeric order.

By default, a container listing can include at most 10,000 items. However, you can use the limit query parameter in a request to specify a smaller maximum number of items. If more than the maximum number of items satisfy the criteria for a request, you can resubmit the request using query parameters to retrieve the next part of the listing.

You use query parameters to limit the items included in a object 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 contents of a container has either of these formats:

  • With the Keystone tenant ID:
    GET /swift/v1/tenant-ID/container-name[?query-parameters] HTTP/1.1
  • With the account name:
    GET /swift/v1/account-name/container-name[?query-parameters] HTTP/1.1

In these formats, query-parameters can be none, one, or a combination of the query parameters described below.

  • delimiter

    The delimiter parameter is a single alphanumeric character used to request all objects in a container up through the first occurrence of the character specified by the parameter.

    The delimiter parameter may be used to request directory listings where the forward (/) slash character is the path delimiter. Using the forward slash delimiter in combination with the prefix parameter, you can list the contents of any directory in the container. Omit the path parameter to list the root directory.

    When you use the delimiter query parameter, the listing includes both objects and directories. If you omit the delimiter query parameter, GET requests only list objects.

    For example, this is the content of an container:

    Items:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    The container listing returned in response to a GET request with the delimiter=/ query parameter contains these items:

    Returned values:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    quarterly_rpts/
    sales/
    sales_quotas_2013.pdf

    The lists of named items included in a listing are subject to any other character specified in the request.

    NoteThis query parameter can only be used to request a container listing, not an account listing.
  • format

    You use the format query parameter to determine the way the response body is formatted. The default method is plain text, but this can be changed to either XML or JSON.

    The Accept request header serves the same function as the format query parameter. If they are both used, the Accept header is ignored.

    Here is an example of how to use the query parameter:

    format=xml
  • limit

    You use the limit query parameter to limit the number of items in the returned container listing to fewer than 10,000.

    For example, the container listing returned in response to a GET request with the limit=5 query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
  • marker

    A container listing is returned in alphabetical order. You use the marker query parameter to only list the items that sort alphabetically after the value of the marker parameter.

    This is useful for paging through long lists of objects in a container. Using the name of the last object in the current page as the marker parameter retrieves the next page of objects.

    For example, the container listing returned in response to a GET request with the marker=mktg/campaign_LiveIt_expenses.xls query parameter contains these items because they all appear after mktg/campaign_LiveIt_expenses.xls:

    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf

    If the string you specify as the value of the marker query parameter is the name of a directory and does not end with a forward slash (/), items that begin with that string followed by a forward slash are omitted from the listing.

  • end_marker

    You use the end_marker query parameter to only list the items that sort alphabetically before the value of the end_marker parameter.

    For example, the container listing returned in response to a GET request with the end_marker=quarterly_rpts/ query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
  • path

    You use the path query parameter to list all objects within the directory of a specified path. If there are subdirectories in the selected path the contents of the subdirectories are not listed. For instance, the following objects are returned in response to GET container request:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    path=quarterly_rpts returns:

    quarterly_rpts/
    quarterly_rpts/budget_proposals/
  • prefix

    You use the prefix query parameter to request a container listing that contains only items with names that begin with the specified character string (the prefix).

    The prefix query parameter is used in conjunction with the delimiter parameter to list the contents of directories.

    For example, the container listing returned in response to a GET request with the prefix=sales query parameter contains only these items:

    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf
Request headers

The table below describes the headers you can use in a request to list the contents of a container.

NameTypeDescription
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"
AcceptString

Set this header to application/json, application/xml, or text/xml. The response body will be serialized in the specified format.

This can also be accomplished with the format query parameter. If you use both at once, the response body defers to the format provided by the query parameter.

Response headers

The table below describes the response headers returned in response to a successful request to list the contents of a container.

NameTypeDescription
Accept-RangesString (Required)Always bytes. This header shows the type of ranges that an object accepts from a Range request header.
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-Container-Bytes-UsedInt (Required)The total amount of bytes of data stored in the container. This number is capped by the X-Container-Meta-Quota-Bytes header.
X-Container-Meta-Quota-BytesStringIf a quota has been set on the amount of bytes that can be stored by this container, this header returns the size, in bytes, of objects that can be stored in the container.
X-Container-Object-CountInt (Required)The total number of objects stored in the container. This number includes all objects in all directories that are in the container. Directories are not included in this number.
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

The response body returned in response to a request to list the contents of a container in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<container name="sales-practice">
     <object>
          <name>mktg/campaign_GoGetEm_expenses.xls</name>
          <hash>D357101A82D4F262E25860284C13EAC58F9A27A6AD70491BC6AAB4FB5113ABBC</hash>
          <bytes>23040</bytes>
          <content_type>application/octet-stream</content_type>
          <last_modified>2014-10-31T12:39:16.000055</last_modified>
          <subdir xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
     </object>
</container>

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

  • Bytes

    Child of the Object element.

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

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

  • Container

    Root element.

  • Content-Type

    Child of the Object element.

    The Content-Type element specifies 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.

  • Hash

    Child of the Object element.

    The Hash element specified the calculated the Base64-encoded MD5 hash of the item.

  • Last_Modified

    Child of the Object element.

    The Last_Modified element specifies the date and time at which the target object was last modified, in Greenwich Mean Time (GMT). The date and time are expressed in this format:

    yyyy-MM-ddTHH:mm:ss.SSSZ

    For example:

    2014-10-20T16:34:27.000135

    Modifying an object means modifying its metadata. You cannot modify the content of an object.

  • Object

    Child of the Container element and container for the Bytes, Content-Type, Hash, Last Modified and subdir xsi:nil elements.

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

  • subdir xsi:nil="true | false"

    Child of the Container element.

    The response body specifies whether the Object element is a sub-directory (true) or object (false).

    The response body lists elements for sub-directories as well as objects. However, because sub-directories have no content, the value of the Bytes element is always 0 (zero) and the value of the Content_Type is always application/octet-stream.

HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to list container contents.

CodeMeaningDescription
200OKThe response body lists the objects.
204No ContentThe response body shows no objects. Either the container has no objects 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.
404Not FoundIf the container does not exist.
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 the items in a directory

Here's a sample GET request for a container listing that lists the objects that are in the mktg directory and, separately, the subdirectories that are in the mktg directory. The requests uses these query parameters:

  • prefix=mktg/

    lists only items that start with mktg/

  • marker=mktg/

    Starts the listing with the item that follows mktg/ by itself

  • delimiter=/

    Treats items that have a forward slash (/) after mktg/ as having a common prefix

Request with curl command line

curl -i -X GET http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance?prefix=mktg&marker=l&delimiter=/" -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Accept: application/xml"

Request headers

GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance?prefix=mktg&marker=mktg&delimiter=/" HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 200 OK
Date: Fri, 31 Oct 2014 16:41:58 GMT
X-Trans-Id: 2a6d516f-b78b-418b-aea3-12fc86316ad4
X-Container-Object-Count: 2
X-Container-Bytes-Used: 46080
X-Container-Meta-Quota-Bytes: 53687091200
X-Container-Read:
X-Container-Write:
Content-Type: application/xml;charset=UTF-8

Deleting a container

You use the HTTP DELETE method to delete a container. To delete a container, you need to have a Keystone or local authentication token for the HSwift account in which the container exists.

You can delete a container only while it's empty. If you try to delete a container that contains any objects, HCP returns a 409 (Conflict) status code and does not delete the container.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to delete a container has either of these formats:

  • With the Keystone tenant ID:
    DELETE /swift/v1/tenant-ID/container-name HTTP/1.1
  • With the account name:
    DELETE /swift/v1/account-name/container-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to delete a container.

NameTypeDescription
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 a response to a successful request to a delete a container.

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-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes tat can be returned in response to a request to delete a container.

CodeMeaningDescription
204No ContentThe container was deleted.
404Not FoundThe container you are trying to delete does not exist in this account.
409ConflictThe container you are trying to delete is not empty.
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: Deleting a container

Here's a sample DELETE request that deletes the container named sales-mktg.

Request with curl command line

curl -i -X DELETE http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mkgt -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

DELETE /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mkgt HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 204 No Content
Date: Fri, 31 Oct 2014 14:06:11 GMT
Content-Length: 0
X-Trans-Id: tx66248155dbb74b6a85f6d-0053fccdcd
Content-Type: application/octet-stream

 

  • Was this article helpful?