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