Checking the existence of an object or 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.

Request line

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

Required headers

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.

Optional headers

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

Response headers

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.

Return codes

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.

CodeMeaningDescription
200OKPossible reasons include:
  • The specified object, object version, delete marker, or folder exists.
  • The application tries to get the labeled holds on an object with an HCP version earlier than 9.1.
304Not Modified

One of these:

  • The request included an If-None-Match header, and the ETag for the specified object or object version matched a value specified by the header.
  • The request included an If-Modified-Since header, and the specified object or object version was not modified after the date and time specified by the header.
403Forbidden

Possible reasons include:

  • The credentials provided with the request are invalid.
  • You do not have read permission for the specified bucket or object.
  • The S3 compatible API is currently disabled for the specified bucket.
404Not Found

One of these:

  • The specified object, object version, or folder does not exist.
  • The specified bucket does not exist.
409ConflictPossible reason includes that the object data is currently being written to HCP.
412Precondition Failed

One of these:

  • The request included an If-Match header, and the ETag for the specified object or object version does not match any of the values specified by the header.
  • The request included an If-Unmodified-Since header, and the specified object or object version was modified after the date and time specified by the header.
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 the existence of an object

Here is a sample HEAD request that checks the existence of an object named sales_quotas_2020.pdf in the finance bucket. Versioning is disabled on the bucket. Because the user has data access permission on the bucket, labeled holds are returned in a JSON format string.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k
     "https://finance.europe.hcp.example.com/sales_quotas_2020.pdf"

Request headers

HEAD /sales_quotas_2020.pdf HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 18 September 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:LDa147ALd+O5Q02LjkGRrXwSGAc=

Response headers

HTTP/1.1 200 OK
Date: Fri, 18 September 2020 17:19:26 GMT
ETag: "62e82b6d3ef16070a8d75ab55c42b80d"
Accept-Ranges: bytes
Last-Modified: Fri, 03 Jan 2020 14:28:48 GMT
Content-Type: application/pdf
X-HCP-Retention: 0
X-HCP-LabelRetentionHold: true
X-HCP-LabelRetentionHold-Labels: '[{"id":"UniqueLabelHold-1","hold":true},
{"id":"UniqueLabelHold-2","hold":true}, {"id":"UniqueLabelHold-3","hold":true}]'
Content-Length: 23166

Example: Retrieving custom metadata for an object version

Here is a sample HEAD request that checks the existence of a version of the object named AcctgBestPractices.doc, which has custom metadata. The request is being made while versioning is enabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k
     "https://finance.europe.hcp.example.com/AcctgBestPractices.doc
     ?versionId=87288758401473"

Request headers

HEAD /AcctgBestPractices.doc?versionId=87288815588289 HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:EUa2evHNUtlw8Xu/1iFdGgWSDc8=

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "26aa5129552e57fc64e10aa5b3911ee2"
Accept-Ranges: bytes
x-amz-version-id: 87288758401473
Last-Modified: Sun, 29 May 2016 14:56:05 GMT
x-amz-meta-author: P.D. Grey,Morgan White,Paris Black
Content-Type: application/msword
Content-Length: 3206178

Example: Checking whether an object has been modified

Here is a sample HEAD request that checks whether the object named AcctgBestPractices.doc has been modified since December 20, 2016, at 23:59:59 GMT. The request is being made while versioning is enabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k
     "https://finance.europe.hcp.example.com/AcctgBestPractices.doc"
     -H "If-Modified-Since: Tue, 20 Dec 2016 23:59:59 +0000"

Request headers

HEAD /AcctgBestPractices.doc HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:Yn7gcia/yqzGRKRC04HaOuD3aH0=
If-Modified-Since: Tue, 20 Dec 2016 23:59:59 +0000

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "764f38262c6e581f678e1ac9b0211ae8"
Accept-Ranges: bytes
x-amz-version-id: 87288815588289
Last-Modified: Thu, 29 Dec 2016 19:42:16 GMT
x-amz-meta-author: Morgan White
Content-Type: application/msword
Content-Length: 3552369

Example: Checking the existence of a folder

Here is a sample HEAD request that checks the existence of a folder named r&d/budget_proposals in the finance bucket. The request is being made while versioning is enabled for the bucket.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k
     "https://finance.europe.hcp.example.com/r&d/budget_proposals/"

Request headers

HEAD /r&d/budget_proposals/ HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Fri, 07 February 2020 17:19:26 +0000
Authorization: AWS bGdyZWVu:4u9bhK0DQF2FLZtT0VVwMKdvm+I=

Response headers

HTTP/1.1 200 OK
Date: Fri, 07 February 2020 17:19:26 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Accept-Ranges: bytes
x-amz-version-id: 87395113368065
Last-Modified: Wed, 18 Jan 2017 14:40:26 GMT
Content-Type: application/octet-stream
Content-Length: 0