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

Content Platform Tenant Management

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