Checking the existence of an object or multiple versions of an object

Content Platform Tenant Management Help

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

You use the HTTP HEAD method to check whether an object, a version of an object, or a range of versions of an object exists in a namespace. These requests also retrieve the metadata for the object without retrieving the object data. The metadata is returned in HTTP response headers.

An HTTP 200 (OK) status code indicates that the requested object or object versions exist. An HTTP 404 (Not Found) status code indicates that the specified URL does not identify the object or its versions. Even if versioning is currently disabled, the method returns a 200 code and metadata if the requested version exists.

Using HEAD with a symbolic link verifies the existence of the object that is the target of the link.

Access permission

To verify the existence of an object or multiple object versions, you need browse permission.

Request header

HEAD /rest/directory/file?version=@version_num HTTP/1.1

The HEAD request to verify the existence of an object or multiple versions has these elements:

  • If you are accessing the namespace as an authenticated user, an Authorization header
  • The URL of the object or symbolic link
Parameter Required Description
directory Yes Folder name.
file Yes Name of the file, including file extension.
version No

One of:

  • Specific version number of the file. For example:
    ?version=80232998058817
  • Range of version IDs, separated by a dash. For example:
    ?version=91728994618369-91728994618372
  • Range of create timestamps, separated by a dash. For example:
    ?version=@1493911519817-@1493911519817
  • 0-, which provides all versions of an object.

These rules apply to the version query parameter:

  • If you omit the parameter, HCP checks the existence of the current version of an object.
  • If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
deleted No

By default, the GET request to retrieve object versions does not include delete records. To retrieve a listing that includes delete records, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Response headers

The following list describes request-specific response headers returned for this operation.

ChangeTimeString
The change time for the object in this format:
DDD, ddmmmyyyyhh:mm:ss GMT
For example, Fri, 18 Sep 2020 21:02:13 GMT.
This header contains the same datetime value as the X-HCP-ChangeTimeMilliseconds and X-HCP-ChangeTimeString headers, but in a format that can be used directly in If-Modified-Since and If-Unmodified-Since request headers.
ETag
The ETag of the object or version enclosed in double quotation marks ("). This header is returned only if the object has an ETag.
X-HCP-ACL
A true or false value indicating whether the object has an ACL.
X-HCP-ChangeTimeMilliseconds
The change time for the object, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that is unique for the change time. For example: 1336483100178.00.
X-HCP-ChangeTimeString
The change time for the object in this format:
yyyy-MM-ddThh:mm:ssZ
In this format, Z represents the offset from UTC and is specified as:
(+|-)hhmm
For example, 2020-09-18T09:18:20-0400 represents the start of the 20th second into 9:18 AM, September 18, 2020, EDT.
X-HCP-CurrentStorageNode
The IP address of a node on which object data is stored. You may get better performance retrieving an object if you use this IP address in the GET request for the object instead of using a host name in the request URL.
This header is returned only if both of these are true:
  • HCP is configured to return the header.
  • HCP has determined that a GET request for the object is likely to have better performance if the request is targeted to the IP address specified by the header.
X-HCP-Custom-Metadata
A true or false value indicating whether the object has any annotations.
X-HCP-CustomMetadataAnnotations
A comma-and-space-separated list containing the names and sizes of all object annotations. Each entry in the list consists of the annotation name, a semicolon (;) and the annotation size in bytes. For example: report_data; 12908.
This header is returned only if X-HCP-Custom-Metadata is true.
X-HCP-Domain
The Active Directory domain that contains the user identified by the X-HCP-Owner header.
This value is an empty string if the X-HCP-Owner header identifies a user account defined in HCP or if the object has no owner.
If the X-HCP-Owner header returns a user account ID or nobody, the value of the X-HCP-Domain header is one of several invalid domains that begin with the percent sign (%). These values have meanings internal to the HCP system.
X-HCP-DPL
The data protection level for the object.
X-HCP-GID
The POSIX group ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions is true:
  • The object was added through a protocol other than NFS and neither the UID nor the GID for the object has been changed.
  • The HCP product-specific owner of the object was changed.
X-HCP-Hash
The cryptographic hash algorithm HCP uses, along with the cryptographic hash value stored for the object, in this format:
X-HCP-Hash: hash-algorithmhash-value
You can use the returned hash value to verify that the stored data is the same as the data you sent. To perform the verification, compare this value with a hash value that you generate from the original data.
The
X-HCP-Hash
header is not returned for multipart objects.
X-HCP-Index
A true or false value indicating whether the object is marked for indexing.
X-HCP-IngestProtocol
The namespace access protocol through which the object was added to the namespace. Possible values are:
  • CIFS_NFS
  • HTTP
  • SMTP
  • WebDAV
If HCP cannot determine the protocol through which the object was added, this value is UNKNOWN.
X-HCP-IngestTime
The time when HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC.
x-HCP-LabelRetentionHold
Specifies whether the object is on labeled hold. A Boolean value (true | false) is 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 object, this header is returned with a list of 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-LastVersionId
The version ID of the last returned object version.
X-HCP-Owner
The user that owns the object.
This value is an empty string if the object has no owner.
This value is nobody for objects that were stored by an authenticated user before the HCP system was upgraded from a release earlier than 5.0. These objects effectively have no owner.
This value is a user account ID if HCP can no longer identify the object owner by username. For example, you would see a user account ID if the HCP user account has been deleted.
X-HCP-Replicated
A true or false value indicating whether the object, has been replicated. The value is true only if the current version of the object, its system metadata, annotations (if any), and ACL (if any) have been replicated.
HCP returns this header only if either of these conditions is true:
  • HCP is configured to return this header, and the request does not include the X-HCP-Get-Replicated header with a value of false.
  • The request includes the X-HCP-Get-Replicated header with a value of true.
X-HCP-ReplicationCollision
A true or false value indicating whether the object is flagged as a replication collision.
X-HCP-Retention
The end of the retention period for the object. Possible values are:
  • A time in seconds since January 1, 1970, at 00:00:00 UTC
  • 0
  • -1
  • -2
X-HCP-RetentionClass
The name of the retention class to which the object belongs.
This value is an empty string if the object is not in a retention class.
X-HCP-RetentionHold
A true or false value indicating whether the object is on hold.
X-HCP-RetentionString
The end of the retention period for the object. Possible values are:
  • A date and time in this format:
    yyyy-MM-ddThh:mm:ssZ

    In this format, Z represents the offset from UTC and is specified as:

    (+|-)hhmm

    For example, 2019-12-14T14:27:20-0500 represents the start of the 20th second into 2:27 PM, December 14, 2019, EST.

  • Deletion Allowed
  • Deletion Prohibited
  • Initial Unspecified
X-HCP-Shred
A true or false value indicating whether HCP will shred the object after the object is deleted.
X-HCP-Size
The size of the object data, in bytes.
X-HCP-SoftwareVersion
The version number of the HCP software.
X-HCP-SymlinkTarget
The path to the target object as specified when the symbolic link was created.
This header is returned only if the URL specifies a symbolic link to an object.
If this header is returned, the X-HCP-ACL value is always false.
X-HCP-Type
The object entity type.
X-HCP-UID
The POSIX user ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions are true:
  • The object was added through a protocol other than NFS and neither the UID nor the GID for the object was changed.
  • The HCP product-specific owner of the object was changed.
X-HCP-VersionId
The version ID of the object.

Response body

Not applicable.

Status codes

The following table describes the HTTP status codes that have specific meaning for this request.

Code Meaning Description
200 OK HCP found the specified object or version and returned its metadata. This code is also returned if the specified URL identifies a directory, not an object.
304 Not Modified

One of:

  • The request specified an If-None-Match header, and the ETag of the requested object or version matches the value in the header.
  • The request specified an If-Modified-Since header, and the object change time is at or before the time specified in the header.
400 Bad Request

The request was not valid. These are some, but not all, of the possible reasons:

  • The URL in the request is not well-formed.
  • The namespace does not exist.
  • The request included an If-Match or If-None-Match header and the object does not yet have an ETag.
  • The request contains an unsupported query parameter or an invalid value for a query parameter.

If more information about the error is available, the HTTP response headers include the HCP product-specific X‑HCP-ErrorMessage header.

404 Not Found

One of:

  • HCP did not find a directory, object, or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted.
  • Any component of the URL except for the last component in the path is a symbolic link to a directory.
412 Precondition Failed

One of:

  • The request specified an If-Match header, and the ETag of the requested object or version does not match the value in the header.
  • The request specified an If-Unmodified-Since header, and the object change time is after the time specified in the header.

Checking the existence of an object

Here is a sample HTTP HEAD request that checks the existence of an object named Q2_2020.ppt in the quarterly_rpts directory.

Request with curl command line

curl -iI -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt"

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q2_2020.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

Request headers

HEAD /rest/quarterly_rpts/Q2_2020.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-CurrentStorageNode: 172.20.27.21
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 9.2.16
ETag: "8d604138ffb0f308a8552a3752e5a1be"
Content-Type: application/vnd.ms-powerpoint
Content-Length: 679116
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Type: object
X-HCP-Size: 679116
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80111794065921
X-HCP-IngestTime: 1334340948
X-HCP-RetentionClass: (SEC17a, A+7y)
X-HCP-RetentionString: 2022-12-19T09:51:47-0400
X-HCP-Retention: 1524131507
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: lgreen
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2020-09-18T05:53:47-0400
Last-Modified: Wed, 18 Sep 2020 09:53:47 GMT

Checking the existence of an object version at a specified time

Here is a sample HTTP HEAD request that checks the existence of a version of an object named Q2_2020.ppt in the quarterly_rpts directory at the specified time of 80232998058817 using the object version ingest time.

Request with curl command line

curl -i -I -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt
    ?version=@1433265536867" > Q2_2020.ppt

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q2_2020.ppt?version=@1433265536867")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

Request headers

HEAD /rest/quarterly_rpts/Q2_2020.ppt?version=@1433265536867 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 18 Sep 2020 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 9.2.16
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
Expires: Fri, 18 Dec 2020 00:00:00 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Disposition: attachment;
Content-Length: 678400
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1433265536
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-CustomMetadataAnnotations:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1433265537266.00
X-HCP-ChangeTimeString: 2020-09-18T13:18:57-0400
Last-Modified: Fri, 18 Sep 2020 17:18:57 GMT

Checking the existence of a range of object versions

Here is a sample HTTP HEAD request that checks the existence of a range of object versions for an object named Q2_2020.ppt in the quarterly_rpts directory. The version range for the object is 80232998058817-80232998058819.

Request with curl command line

curl -i -I -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt
    ?version=80232998058817-80232998058819" > Q2_2020.ppt

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q2_2020.ppt?version=80232998058817-80232998058819")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

Request headers

HEAD /rest/quarterly_rpts/Q2_2020.ppt?version=80232998058817-80232998058819 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Fri, 18 Sep 2020 18:21:14 GMT
X-HCP-ServicedBySystem: finance.europe.hcp.example.com
X-HCP-Time: 1434997274
X-HCP-SoftwareVersion: 9.2.16
X-HCP-LastVersionId: 80232998058819
Content-Length: 678400