Creating a directory
You use the HTTP PUT method to create a directory in a container. To create a directory, you need write permission for the container.
To tell HCP to create a directory instead of an object in response to a PUT request, you need to include a forward slash (/) after the directory's name.
When you create a directory, you specify a name for it. The rules for directory names are the same as the rule for object names.
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 directory has either of these formats:
- With the Keystone tenant ID:
PUT /swift/v1/tenant-ID/container-name/directory-name/ HTTP/1.1
- With the account name:
PUT /swift/v1/account-name/container-name/directory-name/ HTTP/1.1
Request headers
The table below describes the headers you can use in a request to create a directory.
Name | Type | Description |
X-Auth-Token | String |
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" |
Content-Encoding | String | Specifies whether the request body is compressed. If so, enter gzip . |
Content-Length | Integer | Specifies the size, in bytes, of the data being stored. |
Etag | String |
This value is the MD5 checksum of the object content. It is recommended to compute the MD5 checksum of the response body and compare this value with this ETag header. If they differ, the content may have been corrupted. |
Expect | String | Use the Expect header with the value of 100-Continue in combination with the If-None-Match header with the value set to an asterisk (*) to query whether the server already has an object of the same name before any data is sent. |
If-None-Match | String |
Specifies one or more values for comparison with the ETag of the specified source object. If the ETag doesn't match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 412 (Precondition Failed) status code. To specify the values for this header, use this format: "value"[, "value"]... In this format, each value can be any string of more characters and must be enclosed in double quotation marks ("). Alternatively, you can specify a single asterisk (*) as the value of the |
Transfer-Encoding | String | If this header is used, always set to chunked . This header should be used if HCP cannot determine the size of the response body before formulating the response. |
X-Copy-From | String |
Specifies the source container and object in this format: /container-name/source-directory-name You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using |
Response headers
The table below describes the response headers returned in response to a successful request to create a directory.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
ETag | String (Required) | Specifies the ETag for the object. |
Date | Datetime (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-Id | Uuid (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 store an object.
Code | Meaning | Description |
201 | Created | The object has been added to the container. |
408 | Request Timeout | The request has timed out and not completed. It is no longer trying to resent the request. |
409 | Conflict | The object already exists and versioning is not enabled. |
411 | Length Required | Indicates a missing Transfer-Encoding or Content-Length request header. |
412 | Precondition Failed | If using If-None-Match: * header and an object already exists at the specified path. |
422 | Unprocessable Entity | MD5 checksum of the data that is written to the object store does not match the optional ETag value. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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 directory
Here's a sample PUT request that creates a directory named budget_proposals in the r&d directory in the finance container. If the r&d directory doesn't already exist, this request also creates that directory.
Request with curl command line
curl -k -i -X PUT http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/budget_proposals/ -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"
Request headers
PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/budget_proposals/ HTTP/1.1 X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
Response headers
HTTP/1.1 201 Created Date: Fri, 24 Oct 2014 14:29:06 GMT ETag: d41d8cd98f00b204e9800998ecf8427e X-Trans-Id: txfe5244ce53a142288ef97-00541b3b32 Content-Type: application/octet-stream Content-Length: 0