Creating a folder

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP PUT method to create a folder in a bucket. To create a folder, you need write permission for the bucket.

To tell HCP to create a folder instead of an object in response to a PUT request, you can do either these:

  • Include a forward slash (/) or the percent-encoded equivalent (%2F) after the folder name in the request.
  • Include the Content-Type header in the request with a value of x-directory.

In either case, you also need to include the Content-Length header in the request. However, HCP ignores any request body.

When you create a folder, you specify a name for it. The rules for folder names are the same as the rules for object names.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to create a folder has either of these formats:

  • With the bucket name included in the hostname:
    PUT /folder-name[(/|%2F)] HTTP/1.1
  • With the bucket name following the hostname:
    PUT /bucket-name/folder-name[(/|%2F)] HTTP/1.1

Required headers

The list below describes the headers you can use in a request to create a folder.

Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the data being stored. In a request to create a folder, the value of this header should be 0 (zero).
Even if you specify a value greater than zero for this header, no request body is sent to HCP.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.
Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the Date header above.

Optional headers

Content-Type
Specifies the Internet media type of the request body. The only valid value is x-directory.
This header is ignored if the folder name in the request ends with a forward slash (/) or the percent-encoded equivalent (%2F). Otherwise, this header is required.
Transfer-Encoding
Specifies the encoding transformation for the request body. The only valid value is chunked.
Even if you include this header in the request, no request body is sent to HCP.

Response headers

The list below describes the headers returned in response to a successful request to create a folder.

Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always 0 (zero).
Date
The date and time when 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:
Fri, 18 Sep 2020 14:27:05 GMT
ETag
Specifies the ETag for the folder.
Even though a folder has no content, HCP returns an ETag for it. However, because folders have no content, all folders have the same ETag.
x-amz-version-id
Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

Status codes

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

Code Meaning Description
200 OK HCP successfully created the folder.
400 Bad Request Possible reasons include that the request does not include a Content-Length header.
403 Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have permission to create folders in the specified bucket.
  • The S3 compatible API is currently disabled for the specified bucket.
404 Not Found The specified bucket does not exist.
409 Conflict An object or folder with the specified name already exists.
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 folder

Here’s a sample PUT request that creates a folder named budget_proposals in the r&d folder in the finance bucket. If the r&d folder doesn’t already exist, this request also creates that folder. The request is being made while versioning is enabled for the bucket.

Note: s3curl does not support the use of the forward slash (/) as the terminator for the folder name in PUT requests to create a folder.

Request with s3curl command line

./s3curl.pl --id=lgreen --put ~ -- -k
     "https://finance.europe.hcp.example.com/r&d/budget_proposals%2F"
     -H "Content-Length:0"

Request headers

PUT /r&d/budget_proposals%2F HTTP/1.1
Host: finance.europe.hcp.example.com
Transfer-Encoding: chunked
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:VsSmWFRWwTPWPjH+QEs6Z2Qwf84=
Content-Length: 0

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
x-amz-version-id: 87395113368065
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Content-Length: 0