Working with objects

You use the HTTP PUT method to store an object in a bucket. To store an object, you need write permission for the bucket.

For a request to store an object, the request body consists of the data in a specified file. This data becomes the object content.

When you store an object, you specify a name for it. The object name does not need to be the same as the name of the file containing the original data.

If versioning is enabled and you try to store an object with the same name as an existing object, HCP creates a new version of the object. If versioning is disabled and you try to store an object with the same name as an existing object, HCP returns a 409 (Conflict) status code and does not store the object.

You can add custom metadata to an object in the same request as you use to store the object. To do this, you use x-amz-meta- headers.

You can specify an ACL for an object in the same request as you use to store the object. To do this, you use an ACL header. You cannot use an ACL request body when storing an object.

If the ACL you specify in a request to store an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not store the object.

If you are an authenticated user, when you store an object, you become the object owner. If you are accessing the bucket anonymously, the new object has no owner.

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

• With the bucket name included in the hostname:

  PUT /object-name HTTP/1.1

• With the bucket name following the hostname:

  PUT /bucket-name/object-name HTTP/1.1

The next list describes the headers you can use in a request to store an object.

• Authorization

  Specifies user credentials or requests anonymous access.

• Content-Length

  Specifies the size, in bytes, of the data being stored.

• 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.

• Content-MD5

  Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.

  When you store an object, you can use the Content-MD5 request header to ensure the integrity of the object data. The value you specify for this header must be the Base64-encoded MD5 hash of the original file data.

  When you include the Content-MD5 header in a request to store an object, HCP calculates the Base64-encoded MD5 hash of the data it receives and compares that to the header value. If the values don’t match, HCP returns a 400 (Bad Request) status code and does not store the object.

• Content-Type

  Specifies the Internet media type of the data being stored. Valid values are Internet media types (for example, text/plain, application/xml, or image/jpeg).

• Expect

  Tells the application not to send the request body if the request headers are rejected. The only valid value is 100-continue. This value is not case sensitive.

  You can use the Expect request header in a request to store an object to tell the application not to send the request body (the data) to HCP if the request headers are rejected. This prevents unnecessary network bandwidth usage.

• x-amz-acl

  Adds a canned ACL to the bucket.

  This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

• x-amz-grant-full-control

  Grants full control over the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

• x-amz-grant-read

  Grants the browse and read data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

• x-amz-grant-read-acp

  Grants the read ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

• x-amz-grant-write

  Grants the write and delete data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

• x-amz-grant-write-acp

  Grants the write ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

• x-amz-meta-

  Adds custom metadata to the object.

• x-amz-server-side-encryption

  Requests that the response headers include x-amz-server-side-encryption, which indicates whether objects stored in HCP are encrypted. The value of the x-amz-server-side-encryption request header can be any character string.

  When you store an object, you can use the x-amz-server-side-encryption request header to determine whether objects stored in HCP are encrypted. If stored objects are encrypted, the response headers include x-amz-server-side-encryption with a value representing the encryption algorithm and key length HCP is using. If stored objects are not encrypted, the value of the x-amz-server-side-encryption response header is None.

• x-hcp-labelretentionhold

  Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold value pairs.

  • id

    Unique label name. The maximum label size is 64 characters.

  • hold

    Either true or false.

  Example

  x-hcp-labelretentionhold [{"id":"UniqueLabelHold-1","hold":true}, 
  {"id":"UniqueLabelHold-2","hold":true}]

• x-hcp-retention

  Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

• x-hcp-retentionhold

  Specifies whether the object is on hold. This value can be either true or false.

The next list describes the headers returned in response to a successful request to store an object.

• 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 object.

  ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.

• x-amz-server-side-encryption

  Specifies whether objects stored in HCP are encrypted. Possible values are:

  • If objects are encrypted, AES256
  • If objects are not encrypted, None

  This header is returned only if the request headers include x-amz-server-side-encryption.

• x-amz-version-id

  Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

The next table describes HTTP status codes that can be returned in response to a request to store an object.

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.

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

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.

• 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.

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.

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

You use the HTTP HEAD method to check the existence of an object or folder in a bucket. To check the existence of an object, you need read permission for the bucket containing the object or for the object itself. To check the existence of a folder, you need read permission for the bucket.

In response to a request to check the existence of an object or folder, HCP returns a 200 (OK) status code if the object or folder exists and a 404 (Not Found) status code if the object or folder does not exist. If you do not have read permission for the bucket or object, HCP returns a 403 (Forbidden) status code.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to check the existence of an object, object version, or folder has either of these formats:

• With the bucket name included in the hostname:

  HEAD /(object-name[?versionId=version-id])|(folder-name(/|%2F)) HTTP/1.1

• With the bucket name following the hostname:

  HEAD /bucket-name/(object-name[?versionId=version-id])|(folder-name(/|%2F)) HTTP/1.1

The next list describes the required headers to use in a request to check the existence of an object, object version, or folder.

• Authorization

  Specifies user credentials or requests anonymous access.

• 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.

• If-Match

  Specifies one or more values for comparison with the ETag of the specified item. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag does not match 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 one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the If-Match header. All ETags match an asterisk in an If-Match header.

• If-Modified-Since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified item was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 304 (Not Modified) status code.

  To specify the date and time for this header, use one of these formats:

  • DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    For example: Tue, 07 Feb 2017 14:27:05 +0000

  • DDDD, dd-MMM-yyyy HH:mm:ss (+0000|GMT)

    For example: Tuesday, 07-Feb-17 14:27:05 +0000

  • DDD MMM d HH:mm:ss yyyy

    For example: Tue Feb 7 14:27:05 2017

  If the value specified by the If-Modified-Since header does not conform to one of the formats shown above, the header is ignored.

• If-None-Match

  Specifies one or more values for comparison with the ETag of the specified item. If the ETag does not match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 304 (Not Modified) status code.

  To specify the values for this header, use this format:

  "value"[, "value"]...

  In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

• If-Unmodified-Since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified item was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code.

  For valid values, see the description of the If-Modified-Since header above.

The next list describes the headers returned in response to a successful request to check the existence an object, object version, or folder.

• Accept-Ranges

  Indicates that HCP can accept requests for part of the object data, specified as a range of bytes. The value of this header is always bytes.

• Content-length

  Specifies the size, in bytes, of the object, object version, or folder. For a delete marker, this is the size of the object or object version that was deleted.

• Content-Type

  Specifies the Internet media type of the object or object version, or folder. This is one of, in order of precedence:

  • The Internet media type specified by the response-content-type request parameter.
  • The Internet media type specified in the Content-Type header when the object was stored.
  • An Internet media type determined by HCP based on the object name.
  • application/octet-stream if HCP cannot determine the Internet media type. For a folder, the value of the Content-Type header is always application/octet-stream.

• 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 specified object, object version, or folder. For a delete marker, this is the ETag of the object or object version that was deleted.

• Last-Modified

  Specifies the date and time when the object, object version, or folder was last modified, in Greenwich Mean Time (GMT). For a delete marker, this is the date and time when the delete marker was created.

  The date and time are expressed in this format:

  DDD, dd MMM yyyy HH:mm:ss GMT

  For example:

  Tue, 07 Feb 2017 19:46:03 GMT

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

• x-amz-delete-marker

  For requests that specify a version ID, indicates whether the version ID identifies a delete marker. This header is returned only for delete markers and only if versioning is enabled for the bucket. The value is always true.

• x-amz-meta-

  For objects and object versions only, specifies a custom metadata property/value pair. The response headers include one x-amz-meta- header for each applicable pair.

• x-amz-missing-meta

  For objects and object versions only, indicates that the .metapairs annotation for the object or object version does not contain valid XML, that the first line in the annotation does not begin with the metapairs element, or that the specified version ID identifies a delete marker and the deleted object version had an annotation. This header is returned only when applicable. The value is always 1 (one).

• x-amz-version-id

  Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

• x-hcp-labelretentionhold

  Specifies whether the object is on labeled hold. A Boolean value of true or false is returned.

  For a user without privileged data access permission, the response header returns true or false indicating whether there are one or more labeled holds.

  For a user with privileged data access permission:

  • If the response header returns true, an additional header, x-hcp-labelretentionhold-labels, is returned.
  • If the response header returns false, the x-hcp-labelretentionhold-labels header is not returned

• x-hcp-labelretentionhold-labels

  If the object is on labeled hold (x-hcp-labelretentionhold:true) and the user has privileged data access and read permissions on the bucket, this header is returned with a JSON format string specifying all labeled holds.

  Example

  X-HCP-LabelRetentionHold-Labels: [{"id":"UniqueLabelHold-1","hold": true},
  [{"id":"UniqueLabelHold-2","hold": true},[{"id":"UniqueLabelHold-3","hold": true}] 

• x-hcp-retention

  Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

• x-hcp-retentionhold

  Specifies whether the object is on hold. A Boolean value of true or false is returned.

The following table describes HTTP status codes that can be returned in response to a request to check the existence of an object, object version, or folder.

You use the HTTP PUT method with the acl query parameter to add an ACL to an existing object. Adding an ACL to an object replaces any existing ACL in its entirety. You cannot modify an existing ACL in place.

To add an ACL to an object, you need write ACL permission for the bucket containing the object or for the object itself.

You can add an ACL only to the current version of an object. However, the ACL you add applies to all versions of the object.

To add an ACL to an object, you can use either request headers or an ACL request body. You cannot use ACL headers and an ACL request body in the same request.

With ACL headers, you can specify either a canned ACL or individual x-amz-grant- headers. You cannot specify both a canned ACL and an x-amz-grant- header in the same request.

You can use an ACL request body to change the owner of an object. You cannot use ACL headers to do this. To change the owner of an object, you need both write ACL permission for the bucket or object and change owner permission for the bucket.

If you try to add an ACL that specifies a user account that does not exist, HCP returns a 400 (Bad Request) status code and does not add the ACL to the object.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to add an ACL to an object has either of these formats:

• With the bucket name included in the hostname:

  PUT /object-name?acl HTTP/1.1

• With the bucket name following the hostname:

  PUT /bucket-name/object-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

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

• Authorization

  Specifies user credentials or requests anonymous access.

• 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.

• Content-Length

  Specifies the size, in bytes, of the request body.

  This header is required when you’re using an ACL request body to add an ACL to an object. If you’re using ACL headers to add the ACL, the Content-Length header is invalid.

• Content-Type

  Specifies the Internet media type of the request body. This header is valid only when the ACL is specified in the request body. The only valid values are application/xml and text/xml.

• x-amz-acl

  Adds a canned ACL to the bucket.

  This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

• x-amz-grant-full-control

  Grants full control over the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

• x-amz-grant-read

  Grants the browse and read data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

• x-amz-grant-read-acp

  Grants the read ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

• x-amz-grant-write

  Grants the write and delete data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

• x-amz-grant-write-acp

  Grants the write ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

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

• Content-length

  Specifies the size, in bytes, of the response body. In response to a successful request to add an ACL to 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

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to an object.

You use the HTTP GET method with the acl query parameter to retrieve the ACL for an object. To retrieve the ACL for an object, you need read ACL permission for the bucket containing the object or for the object itself.

The object ACL is returned in an XML response body. The format of the response body is the same as the format you use for the ACL request body when you add an ACL to a bucket.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to retrieve an object ACL has either of these formats:

• With the bucket name included in the hostname:

  GET /object-name?acl HTTP/1.1

• With the bucket name following the hostname:

  GET /bucket-name/object-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

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

• Authorization

  Specifies user credentials or requests anonymous access.

• 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.

• x-hcp-pretty-print

  Optionally, requests that the XML response body be formatted for readability. Valid values are:

  • true

    Format the XML response body for readability.

  • false

    Do not apply any special formatting to the XML response body.

  The default is false.

  The values true and false are not case sensitive.

The list below describes the headers returned in response to a successful request to retrieve an object ACL.

• Content-Type

  Specifies the Internet media type of the response body. For a request to retrieve an object ACL, the value of this header is always application/xml;charset=UTF-8.

• 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

• Transfer-Encoding

  Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.

The table below describes HTTP status codes that can be returned in response to a request to retrieve an object ACL.

You use the HTTP PUT method with the x-amz-copy-source header to copy an object from one location to another. The source and target locations can be two different buckets within the same tenant, or they can be the same bucket. You can specify a name for the target object that is different from the name of the source object.

To copy an object, you need read permission for the bucket containing the source object or for the source object itself, and write permission for the target bucket.

By default, a copy operation copies the current version of the source object specified in the request. If versioning is enabled for the source bucket, you can use the versionId query parameter with the source object specification to copy a specific version of the object.

• If the version identified by the versionId parameter is a delete marker, HCP returns a 503 (Service Unavailable) status code.
• If the current version of the source object is a delete marker and you do not specify a version ID, HCP returns a 404 (Not Found) status code.

HCP does not copy version IDs with objects. The object created by a copy operation has its own version ID.

HCP also does not copy ACLs with objects. However, in the copy request, you can specify an ACL for the target object. To do this, you need to use ACL headers. You cannot use an ACL request body when copying an object. If the ACL you specify in a request to copy an object is invalid, HCP returns a 400 (Bad Request) or 501 (Not Implemented) status code and does not copy the object.

By default, HCP copies any custom metadata for the source object to the target object. However, in the copy request, you can specify replacement custom metadata to be used for the target object. To apply this custom metadata to the target object, you need to include the x-amz-metadata-directive header with a value of REPLACE in the copy request.

If you are an authenticated user, when you copy an object, you become the owner of the target object. If you are accessing the bucket anonymously, the target object has no owner.

In response to a request to copy an object, HCP returns an XML response body containing the ETag and last modification date of the target object.

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

• With the bucket name included in the hostname:

  PUT /target-object-name HTTP/1.1

• With the bucket name following the hostname:

  PUT /target-bucket-name/target-object-name HTTP/1.1

The next list describes the headers you can use in a request to copy an object.

• Authorization

  Specifies user credentials or requests anonymous access.

• Content-Type

  Specifies the Internet media type of the data being copied. Valid values are Internet media types (for example, text/plain, application/xml, or image/jpeg).

• 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-copy-source

  Specifies the source bucket and object or object version, in this format:

  /bucket-name/source-object-name[?versionId=source-object-version-id]

  The initial forward slash (/) is required.

  Valid values for source-object-version-id are the IDs of versions of the source object specified in the request.

  The versionId query parameter is not case sensitive.

  If you include the versionId query parameter in the x-amz-copy-source header with an invalid value while versioning is enabled, HCP returns a 404 (Not Found) status code and does not copy the object.

  If you include the versionId query parameter in the x-amz-copy-source header while versioning is disabled, the parameter is ignored, and the current version of the specified object is used as the source for the copy operation.

• 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.

• x-amz-acl

  Adds a canned ACL to the bucket.

  This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

• x-amz-copy-source-if-match

  Specifies one or more values for comparison with the ETag of the specified source object or object version. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag does not match any of the specified values, HCP returns a 412 (Precondition Failed) status code and does not copy the object.

  To specify the values for this header, use this format:

  "value"[, "value"]...

  In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the x-amz-copy-source-if-match header. All ETags match an asterisk in an x-amz-copy-source-if-match header.

• x-amz-copy-source-if-modified-since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified source object or object version was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 412 (Precondition Failed) status code and does not copy the object.

  To specify the date and time for this header, use one of these formats:

  • DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    For example: Tue, 07 Feb 2017 14:27:05 +0000

  • DDDD, dd-MMM-yyyy HH:mm:ss (+0000|GMT)

    For example: Tuesday, 07-Feb-17 14:27:05 +0000

  • DDD MMM d HH:mm:ss yyyy

    For example: Tue Feb 7 14:27:05 2017

  If the value specified by the x-amz-copy-source-if-modified-since header doesn’t conform to one of the formats shown above, the header is ignored.

• x-amz-copy-source-if-none-match

  Specifies one or more values for comparison with the ETag of the specified source object or object version. 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 and does not copy the object.

  To specify the values for this header, use this format:

  "value"[, "value"]...

  In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the x-amz-copy-source-if-match header. No ETags match an asterisk in an x-amz-copy-source-if-match header.

• x-amz-copy-source-if-unmodified-since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified source object or object version was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code and does not copy the object.

  For valid values for this header, see the description of the x-amz-copy-source-if-modified-since header above.

• x-amz-grant-full-control

  Grants full control over the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

• x-amz-grant-read

  Grants the browse and read data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

• x-amz-grant-read-acp

  Grants the read ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

• x-amz-grant-write

  Grants the write and delete data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

• x-amz-grant-write-acp

  Grants the write ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

• x-amz-meta-

  Adds custom metadata to the target object.

• x-amz-metadata-directive

  Tells HCP whether to use the custom metadata, if any, for the source object or object version as the custom metadata for the target object or to use the custom metadata, if any, specified in the copy request. Valid values are:

  • COPY

    Use the custom metadata for the source object or object version.

  • REPLACE

    Use the custom metadata specified in the copy request.

  These values are case sensitive.

  The default is COPY.

• x-amz-server-side-encryption

  Requests that the response headers include x-amz-server-side-encryption, which indicates whether objects stored in HCP are encrypted. The value of the x-amz-server-side-encryption request header can be any character string.

• x-hcp-pretty-print

  Optionally, requests that the XML response body be formatted for readability. Valid values are:

  • true

    Format the XML response body for readability.

  • false

    Do not apply any special formatting to the XML response body.

  The default is false.

  The values true and false are not case sensitive.

• x-hcp-labelretentionhold

  Specifies whether to place one or more labeled holds on the object and the associated labeled hold IDs. The values passed with this header are in a JSON format string containing one or more id and hold-value pairs.

  • id

    Unique label name. The maximum label size is 64 characters.

  • hold

    Either true or false.

  Examples

  • Place two labeled holds on the object.

    x-hcp-labelretentionhold [{"id":"LabelHold-1","hold":true}, 
    {"id":"LabelHold-2","hold":true}]

  • Remove a labeled hold from the object.

    x-hcp-labelretentionhold [{"id":"LabelHold-2","hold":false}]

• x-hcp-retention

  Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

• x-hcp-retentionhold

  Specifies whether the object is on hold. This value can be either true or false.

The list below describes the headers returned in response to a successful request to copy an object.

• Content-Type

  Specifies the Internet media type of the response body. For a request to copy an object, the value of this header is always application/xml;charset=UTF-8.

• 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 object.

  ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.

• Transfer-Encoding

  Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.

• x-amz-copy-source-version-id

  Specifies the version ID of the source object. This header is returned only while versioning is enabled for the source bucket.

• x-amz-server-side-encryption

  Specifies whether objects stored in HCP are encrypted. Possible values are:

  • If objects are encrypted, AES256
  • If objects are not encrypted, None

  This header is returned only if the request headers include x-amz-server-side-encryption.

• x-amz-version-id

  Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

HCP returns information about the target object that results from a successful copy request in an XML response body.

The next list describes the XML elements in the response body returned in response to a request to copy an object. The elements are listed in alphabetical order.

• CopyObjectResult

  Root element.

• ETag

  Child of the CopyObjectResult element.

  The ETag element specifies the ETag for the target object.

• LastModified

  Child of the CopyObjectResult element.

  The LastModified element specifies the date and time when 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:

  2020-02-18T19:46:03.856Z

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

The table below describes HTTP status codes that can be returned in response to a request to copy an object.

You can use the x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-modified-since, and x-amz-copy-source-if-unmodified-since request headers to make copy requests conditional:

• The x-amz-copy-source-if-match and x-amz-copy-source-if-none-match headers compare the ETag of the source object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.
• The x-amz-copy-source-if-modified-since and x-amz-copy-source-if-unmodified-since headers compare the date and time the source object or object version was last modified to a date and time that you specify.

If the source object or object version:

• Meets all the conditions specified by the conditional headers included in the request, HCP performs the copy operation.
• Does not meet all the conditions specified by the conditional headers included in the request, HCP returns a 412 (Precondition Failed) status code and does not copy the object.

If a request includes multiple different conditional headers, HCP processes any x-amz-copy-source-if-match and x-amz-copy-source-if-none-match headers before any x-amz-copy-source-if-modified-since or x-amz-copy-source-if-unmodified-since headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the others.

You use the HTTP GET method to retrieve an object from a bucket. Retrieving an object means retrieving the object data. To retrieve an object, you need read permission for the bucket containing the object or for the object itself.

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

• With the bucket name included in the hostname:

  GET /object-name[?versionId=version-id] HTTP/1.1

• With the bucket name following the hostname:

  GET /bucket-name/object-name/object-name[?versionId=version-id] HTTP/1.1

The next list describes the headers you can use in a request to retrieve an object.

• Authorization

  Specifies user credentials or requests anonymous access.

• 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.

• If-Match

  Specifies one or more values for comparison with the ETag of the specified object or object version. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag does not match 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 one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the If-Match header. All ETags match an asterisk in an If-Match header.

• If-Modified-Since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 304 (Not Modified) status code.

  To specify the date and time for this header, use one of these formats:

  • DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

    For example: Tue, 07 Feb 2017 14:27:05 +0000

  • DDDD, dd-MMM-yyyy HH:mm:ss (+0000|GMT)

    For example: Tuesday, 07-Feb-17 14:27:05 +0000

  • DDD MMM d HH:mm:ss yyyy

    For example: Tue Feb 7 14:27:05 2017

  If the value specified by the If-Modified-Since header doesn’t conform to one of the formats shown above, the header is ignored.

• If-None-Match

  Specifies one or more values for comparison with the ETag of the specified object or object version. 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 304 (Not Modified) status code.

  To specify the values for this header, use this format:

  "value"[, "value"]...

  In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

  Alternatively, you can specify a single asterisk (*) as the value for the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

• If-Unmodified-Since

  Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object or object version was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code.

  For valid values for this header, see the description of the If-Modified-Since header above.

• Range

  You can use the Range header in a GET request to retrieve only part of an object or object version. By using the Range header, you can limit the amount of data returned, even when you don’t know the size of the object.

  The value of the Range header is the range of bytes you want to retrieve. The first byte of the data for an object is in position 0 (zero), so a range of 1-5 specifies the second through sixth bytes, not the first through fifth.

  To specify a byte range in a range header, you use this format:

  Range: bytes=byte-range

  The list below shows the valid values for byte-range.

  • start-position–end-position

    Bytes in start-position through end-position, inclusive. If end-position is greater than the size of the object data, HCP returns the bytes in start-position through the end of the data.

    Valid values for start-position and end-position are integers greater than or equal to zero.

    For the specified range to be valid, end-position must be greater than or equal to start-position.

  • start-position–

    Bytes in start-position through the end of the object data.

    Valid values for start-position are integers greater than or equal to zero.

  • –offset-from-end

    Bytes in the offset-from-end position, counted back from the last position in the object data, through the end of the object data. If offset-from-end is greater than the size of the object data, HCP returns the complete object data.

    Valid values for offset-from-end are integers greater than or equal to zero.

  These considerations apply to Range header values:

  • If you specify a valid range in which the start position is less than the size of the object data, HCP returns the requested range of data with a 206 (Partial Content) status code.
  • If you specify a valid range in which the start position is greater than or equal to the size of the object data, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.
  • If you specify an offset of zero, HCP returns a 416 (Requested Range Not Satisfiable) status code and does not return any data.
  • If you specify an invalid value (for example, a value in which the start position is greater than the end position, HCP ignores the Range header and returns the complete object data with a status code of 200 (OK).

  A GET request to retrieve a range of bytes in a multipart object is most efficient when the start and end bytes for the range are aligned with the start and end bytes for one or more of the parts uploaded to create the object.

  You cannot retrieve a part of an in-progress multipart upload.

The next list describes the headers returned in response to a successful request to retrieve an object.

• Accept-Ranges

  Indicates that HCP can accept requests for part of the object data, specified as a range of bytes. The value of this header is always bytes.

• Content-Length

  Specifies the size, in bytes, of the returned data.

• Content-Range

  Specifies the range of bytes retrieved out of the total size of the object data. This header is returned only if the request headers include Range.

• Content-Type

  Specifies the Internet media type of the object or object version. This is one of, in order of precedence:

  • The Internet media type specified by the response-content-type request parameter.
  • The Internet media type specified in the Content-Type header when the object was stored.
  • An Internet media type determined by HCP based on the object name.
  • application/octet-stream if HCP cannot determine the Internet media type.

• 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 object.

  ETags are useful for making object-level operations conditional based on the object content. Operations that can be made conditional are checking the existence of an object, copying an object, and retrieving an object.

• Last-Modified

  Specifies the date and time when the object or object version was last modified, in Greenwich Mean Time (GMT). For a delete marker, this is the date and time when the delete marker was created.

  The date and time are expressed in this format:

  DDD, dd MMM yyyy HH:mm:ss GMT

  For example:

  Tue, 17 Feb 2017 19:46:03 GMT

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

• x-amz-meta-

  For objects and object versions only, specifies a custom metadata property/value pair. The response headers include one x-amz-meta- header for each applicable pair.

• x-amz-missing-meta

  For objects and object versions only, indicates that the .metapairs annotation for the object or object version does not contain valid XML, that the first line in the annotation does not begin with the metapairs element, or that the specified version ID identifies a delete marker and the deleted object version had an annotation. This header is returned only when applicable. The value is always 1 (one).

• x-amz-version-id

  Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

• x-hcp-labelretentionhold

  Specifies whether the object is on labeled hold. Either true or false is returned.

  For a user without privileged data access permission, the response header returns true or false indicating whether there are one or more labeled holds.

  For a user with privileged data access permission:

  • If the response header returns true, an additional header, x-hcp-labelretentionhold-labels, is returned.
  • If the response header returns false, the x-hcp-labelretentionhold-labels header is not returned.

• x-hcp-labelretentionhold-labels

  If the object is on labeled hold (x-hcp-labelretentionhold:true) and the user has privileged data access and read permission on the bucket, this header is returned with a JSON format string specifying all labeled holds.

  Example

  x-hcp-labelretentionhold-labels: [{"id":"UniqueLabelHold-1","hold": true},
  [{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]

• x-hcp-retention

  Specifies the retention value for the object being stored. This value can be a fixed date, an offset, a retention class, or a special value.

• x-hcp-retentionhold

  Specifies whether the object is on hold. Either true or false is returned.

The next table describes HTTP status codes that can be returned in response to a request to retrieve an object.

You can choose to retrieve an object or object version only if its ETag and/or last modification date and time meet certain criteria. You might do this, for example, in an application that maintains a local cache of frequently used objects. With such an application, you can reduce the load on HCP and the network by retrieving objects only if they have changed since they were cached.

You use the If-Match, If-None-Match, If-Modified-Since, and If-Unmodified-Since request headers to make GET requests conditional:

• The If-Match and If-None-Match headers compare the ETag for the requested object or object version to one or more values that you specify. Typically, each value is the ETag for an object or object version of interest.
• The If-Modified-Since and If-Unmodified-Since headers compare the date and time the requested object or object version was last modified to a date and time that you specify.

If the requested object or object version meets all the conditions specified by the conditional headers included in the request, HCP returns the object data. If the requested object or object version does not meet the condition specified by:

• An If-Match or If-Unmodified-Since header, HCP returns a 412 (Precondition Failed) status code and does not return the object data
• An If-None-Match or If-Modified-Since header, HCP returns a 304 (Not Modified) status code and does not return the object data

If a request includes multiple different conditional headers, HCP processes any If-Match and If-None-Match headers before any If-Modified-Since or If-Unmodified-Since headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the rest.

In a request to retrieve an object or object version, you can specify values to be returned in certain response headers. The values you specify in the request override any values that might otherwise be returned for those headers. The headers you can override are returned only in response to a successful request.

To specify response header values, you can use the request headers listed in the table below. The valid values for each request header are the valid values for the corresponding response header.

This book does not describe the response headers listed above, with the exception of Content-Type. For information about the other response headers, see http://www.w3.org/Protocols/rfc2616/rfc2616.html.

You use the HTTP DELETE method to delete an object or folder in a bucket. To delete an object, you need delete permission for the bucket containing the object or for the object itself. To delete a folder, you need delete permission for the bucket.

• You cannot delete an object or any version of that object if the object is under retention or on hold.
• When you delete an object while versioning is enabled, HCP:
  • Retains the current version of the object as an old version. The version ID does not change.
  • Creates a delete marker as the new current version of the object. A delete marker is a special version of an object that indicates that a version of the object has been deleted.

    A delete marker has a version ID but does not have any data or metadata. When you delete an object while versioning is enabled, the version ID of the delete marker is different from the version ID of the object you deleted.

• When you delete an object while versioning is disabled, HCP changes the current version of the object to a delete marker and does not change the version ID.
• If you try to delete an object where the current version is a delete marker, HCP returns a 204 (No Content) status code.
• If you inadvertently delete an object, you can recover it from an old version. You can recover an object only while versioning is enabled.

  To recover an object, use a PUT request to copy the object to itself. Use the versionId query parameter with the source object specification to specify which version of the object you want to use for recovery.

  You cannot use a delete marker to recover an object.

  You cannot recover an object from an old version that has been pruned.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to delete an object, an object version, or a folder has either of these formats:

• With the bucket name included in the hostname:

  DELETE /(object-name|(folder-name(/|%2F))) HTTP/1.1

• With the bucket name following the hostname:

  DELETE /bucket-name/(object-name|(folder-name(/|%2F))) HTTP/1.1

The list below describes the headers you can use in a request to delete an object, object version, or folder.

• Authorization

  Specifies user credentials or requests anonymous access.

• 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.

• x-hcp-privileged

  If you have privileged permission and the bucket allows it, this enables a privileged delete on an object that is under retention. The valid value for this header is a text string of up to 1,024 characters long, which can contain any valid UTF-8 characters, including white space.

The list below describes the headers returned in response to a successful request to delete an object, object version, or folder.

• 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

• x-amz-delete-marker

  Indicates either of these:

  • The version of the object with the version ID specified by the x-amz-version-id header has been deleted.
  • The version of the object with the version ID that immediately precedes the version ID specified by the x-amz-version-id header has been deleted.

  The value of this header is always true.

  This header is returned only while versioning is enabled for the bucket.

• x-amz-version-id

  Specifies the version ID of the object. This header is returned only while versioning is enabled for the bucket.

The table below describes HTTP status codes that can be returned in response to a request to delete an object, object version, or folder.

You use the HTTP POST method to delete multiple objects in a bucket. To delete multiple objects, you need delete permission for the bucket containing the objects or for the objects themselves. You cannot use this method with the S3 compatible API to delete:

• Objects that are under retention.
• Objects that are on hold.
• Delete markers of objects.
• Multiple versions of objects.

Since the S3 compatible API currently does not support deleting multiple objects based on version ID, if you try to delete objects with multiple versions, only the current versions of the objects are deleted.

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

• With the bucket name included in the hostname:

  POST /?delete HTTP/1.1

• With the bucket name following the hostname:

  POST /bucket-name?delete HTTP/1.1

The list below describes the headers you can use in a request to delete multiple objects.

• Authorization

  Specifies user credentials or requests anonymous access.

• Content-MD5

  Directs HCP to check the integrity of the data it receives by comparing a Base64-encoded MD5 hash of that data to the value specified by this header. The valid value for this header is the Base64-encoded MD5 hash of the data in the request body.

• 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.

• Content-Length

  Specifies the size, in bytes, of the data being uploaded.

• 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.

• x-hcp-privileged

  If you have privileged permission and the bucket allows it, this enables a privileged delete on an object that is under retention. The valid value for this header is a text string of up to 1,024 characters long, which can contain any valid UTF-8 characters, including white space.

The list below describes the XML elements in the request body to delete multiple objects. The elements are listed in alphabetical order.

• Delete

  Root element.

• Key

  Child of the Object element.

  The Key element specifies the name of the object to delete.

• Object

  Child of the Delete element.

  The Object element specifies the delete request for an object.

• Quiet

  Child of the Delete element.

  The Quiet element, when its value is set to true, enables quiet mode for the request.

The list below describes the headers returned in response to a successful request to delete multiple objects.

• Content-Length

  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 header is 0 (zero).

• Content-Type

  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.

• 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

HCP returns information about the objects that were successfully deleted and the objects that were not successfully deleted from a delete request in an XML response body.

The list below describes the XML elements in the response body returned in response to a request to delete multiple objects. The elements are listed in alphabetical order.

• Code

  Child of the Error element.

  The Code element specifies the status code for the error.

• DeleteMarker

  Child of the Deleted element.

  The DeleteMarker element specifies whether the request accessed a delete marker.

• DeleteMarkerVersionId

  Child of the Deleted element.

  The DeleteMarkerVersionId element specifies the version ID of the delete marker accessed by the request. Currently, Not Implemented is returned with this element.

• DeleteResult

  Root element.

• Deleted

  Child of the DeleteResult element.

  The Deleted element specifies the name of the object that the S3 compatible API successfully deleted.

• Error

  Child of the DeleteResult element.

  The Error element specifies the name of the object that was not deleted and describes the error that was encountered.

• Key

  Child of the Deleted element or the Error element.

  The Key element specifies the name of the object that the S3 compatible API attempted to delete.

• Message

  Child of the Error element.

  The Message element provides more information about the error.

• VersionId

  Child of the Deleted element or the Error element.

  The VersionId element specifies the version ID of the object that the S3 compatible API attempted to delete. The version ID of only the current version of the object is returned.

The table below describes HTTP status codes that can be returned in response to a request to delete multiple objects.